« 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
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
- Ajouter une étape
wp theme list --format=jsonà la fin du script de déploiement - Comparer la version retournée à celle attendue dans l’en-tête du
style.cssdéployé - 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.
