« The theme is missing the style.css stylesheet » : causes et correctifs

Symptôme. Un client de la Clinique du Parc a tenté d’installer lui-même un thème téléchargé sur le site d’un développeur indépendant, via Apparence > Thèmes > Ajouter > Téléverser un thème. Résultat : un message rouge sans appel, « The theme is missing the style.css stylesheet. » ou, en français, « Le thème ne possède pas de feuille de style style.css. » L’installation échoue immédiatement, sans autre indication. Ce message revient assez souvent en support pour mériter un diagnostic complet, cause par cause.

Cet article suit une logique symptôme puis diagnostic puis correctif, dans l’ordre où il faut réellement vérifier les choses, en commençant par la cause la plus fréquente.

Diagnostic : le dossier imbriqué dans l’archive

Dans l’immense majorité des cas, le problème vient de la structure du fichier ZIP téléversé. WordPress s’attend à trouver style.css directement à la racine de l’archive, ou dans un unique dossier à la racine qui contient lui-même tous les fichiers du thème. Si l’archive a été créée en compressant un dossier parent qui contient un sous-dossier contenant le vrai thème, WordPress ne trouve jamais style.css au bon niveau :

mon-theme.zip
└── Téléchargements/
    └── mon-theme/
        ├── style.css
        ├── functions.php
        └── ...

La structure attendue est plus directe :

mon-theme.zip
└── mon-theme/
    ├── style.css
    ├── functions.php
    └── ...

Correctif

Il faut décompresser l’archive fautive, vérifier à quel niveau se trouve réellement style.css, puis recompresser uniquement le dossier qui le contient directement. Sur macOS, compresser un dossier via le Finder ajoute parfois un niveau supplémentaire si l’on sélectionne le mauvais élément avant de faire clic droit puis « Compresser ». Sur Windows, le même problème survient si l’on compresse le contenu d’un dossier fraîchement extrait sans revérifier son arborescence.

Diagnostic : l’en-tête de style.css absent ou mal formé

Même avec une archive bien structurée, WordPress peut afficher la même erreur si le fichier style.css ne contient pas l’en-tête de commentaire attendu en tout début de fichier, ou si ce commentaire ne précise pas au minimum le nom du thème :

/*
Theme Name: Clinique Vitrine
Theme URI: https://exemple.fr/
Author: Agence
Description: Thème sur mesure pour cabinets vétérinaires.
Version: 1.0.0
*/

Si ce bloc de commentaire est absent, placé plus bas dans le fichier, ou si la ligne Theme Name: manque, WordPress considère que le fichier trouvé n’est pas une feuille de style de thème valide et affiche l’erreur, même si un fichier nommé style.css existe bel et bien dans l’archive.

Diagnostic : le cas particulier du thème enfant mal nommé

Un thème enfant possède obligatoirement son propre style.css, distinct de celui du thème parent, avec un en-tête qui référence ce dernier via Template: :

/*
Theme Name: Clinique Vitrine Enfant
Template: clinique-vitrine
*/

Deux erreurs reviennent régulièrement à ce niveau : soit le dossier du thème enfant est zippé avec la même erreur d’imbrication que pour un thème classique, soit la valeur de Template: ne correspond pas exactement au nom du dossier du thème parent tel qu’il existe sur le serveur cible — un problème différent qui provoque un message d’erreur distinct, mais qu’on confond parfois avec celui-ci lors d’un diagnostic rapide.

Méthode de vérification rapide avant réimport

1. Extraire l’archive localement et vérifier, dans l’explorateur de fichiers, que style.css apparaît bien au premier niveau visible en ouvrant le ZIP.
2. Ouvrir ce fichier et confirmer la présence d’un bloc de commentaire en tout début, avec au minimum la ligne Theme Name:.
3. Recompresser uniquement le contenu du dossier du thème, jamais le dossier parent qui l’entoure.
4. Retenter l’import via Apparence > Thèmes > Ajouter, ou déposer directement le dossier corrigé par FTP dans wp-content/themes/ si l’accès serveur est disponible — cette méthode contourne d’ailleurs entièrement la limite de taille de téléversement imposée par certains hébergements.

Neuf fois sur dix, cette erreur ne vient pas d’un thème cassé mais d’une archive mal préparée. Le réflexe le plus rentable reste de vérifier la structure du ZIP avant de suspecter quoi que ce soit d’autre.

Prévention

Pour éviter que ce problème ne se reproduise sur les livraisons de thèmes de l’agence, la pratique retenue consiste à toujours vérifier l’archive finale en la décompressant intégralement sur une machine propre avant envoi, plutôt que de faire confiance à l’outil de compression utilisé. Ce contrôle prend trente secondes et évite un aller-retour de support pour un client qui n’a, la plupart du temps, commis aucune erreur de manipulation de son côté. Les écrans blancs liés à des erreurs PHP relèvent d’un diagnostic complètement différent, non traité ici.