# « The theme directory does not contain a valid theme » : dépôt mal structuré

> Un pipeline de déploiement automatisé pousse un thème qui refuse de s'activer. Diagnostic d'une arborescence de dépôt mal structurée, et correctif durable.

- Auteur : Clément Hadrot
- Publié le : 2025-01-07
- Mis à jour le : 2025-01-07
- Catégorie : Thèmes
- URL : https://wpmoderne.dev.wordpress-developpement.fr/themes/theme-directory-does-not-contain-valid-theme/

## L’essentiel

- L'erreur vient presque toujours d'un dossier racine mal placé
- wp theme list confirme ce que WordPress voit vraiment
- Le correctif doit vivre dans le script de déploiement, pas à la main

« The theme directory does not contain a valid theme » : ce message s'affiche dans l'administration WordPress après un déploiement automatisé qui, en apparence, s'était pourtant terminé sans erreur. Le pipeline avait bien copié les fichiers vers le serveur, mais WordPress refusait obstinément de reconnaître le thème comme valide, alors que le même code fonctionnait parfaitement en local.

## Symptôme : un thème invisible ou fantôme

Dans l'administration, la liste des thèmes n'affichait tout simplement pas la nouvelle version déployée, ou l'affichait avec une icône d'erreur générique. En ligne de commande, `wp theme list` confirmait le problème plus clairement que l'interface graphique :

```
$ wp theme list
+------------------+----------+--------+---------+
| name             | status   | update | version |
+------------------+----------+--------+---------+
| twentytwentyfive | active   | none   | 1.2     |
| mon-theme        | inactive | none   |         |
+------------------+----------+--------+---------+
```

Un thème sans numéro de version affiché, ou complètement absent de cette liste, indique presque toujours que WordPress ne trouve pas de fichier `style.css` valide à l'endroit attendu, c'est-à-dire directement à la racine du dossier du thème dans `wp-content/themes/`.

## Diagnostic : une archive qui contient un dossier de trop

> L'essentiel à retenir : L'erreur vient presque toujours d'un dossier racine mal placé ; wp theme list confirme ce que WordPress voit vraiment ; Le correctif doit vivre dans le script de déploiement, pas à la main

Le script de déploiement générait une archive du dépôt Git via `git archive`, puis l'extrayait sur le serveur dans `wp-content/themes/mon-theme/`. Le problème : le dépôt Git contenait lui-même un sous-dossier `theme/` à sa racine, hérité d'une ancienne organisation du projet où plusieurs éléments cohabitaient dans le même dépôt. L'extraction plaçait donc `style.css` dans `wp-content/themes/mon-theme/theme/style.css`, un niveau trop profond pour que WordPress le détecte.

```
wp-content/themes/mon-theme/
└── theme/
    ├── style.css
    ├── functions.php
    └── index.php
```

WordPress attend `style.css` directement à la racine du dossier nommé d'après le thème, avec un en-tête valide contenant au minimum `Theme Name:`. Un niveau de dossier supplémentaire, même avec un contenu par ailleurs correct, suffit à produire exactement ce message d'erreur.

## Correctif : aplatir l'archive au bon endroit

Le script de déploiement a été corrigé pour extraire le contenu du sous-dossier `theme/` directement à la racine de destination, plutôt que l'ensemble du dépôt :

```
git archive HEAD:theme/ --format=tar | \
  ssh deploiement@serveur "tar -x -C /var/www/site/wp-content/themes/mon-theme/"
```

Le paramètre `HEAD:theme/` indique à `git archive` de partir directement du contenu du sous-dossier plutôt que de la racine du dépôt, ce qui évite d'avoir à corriger l'organisation du dépôt lui-même. Un simple `wp theme list` après ce correctif a confirmé la présence du numéro de version attendu.

### Prévention : vérifier automatiquement après chaque déploiement

1. Ajouter une étape `wp theme list --format=json` à la fin du script de déploiement
2. Comparer la version retournée à celle attendue dans l'en-tête du `style.css` déployé
3. Faire échouer le pipeline si le thème n'apparaît pas actif avec le bon numéro de version

Cette vérification prend moins d'une seconde à exécuter et transforme un problème silencieux, découvert parfois plusieurs heures après le déploiement, en échec immédiat et explicite du pipeline.

> Un déploiement qui se termine sans erreur n'a pas forcément réussi : seule une vérification côté WordPress confirme que le thème est réellement reconnu.

## En résumé

Ce message d'erreur pointe presque toujours vers la même cause : un fichier `style.css` qui ne se trouve pas directement à la racine du dossier attendu par WordPress. La correction rapide consiste à ajuster le chemin d'extraction de l'archive de déploiement ; la correction durable consiste à ajouter une vérification automatisée via `wp theme list` juste après, pour ne plus jamais découvrir le problème depuis l'administration.