Résoudre l'écran blanc de la mort dans WordPress

L’écran blanc de la mort (« white screen of death ») de WordPress est une erreur fatale PHP dont l’affichage des erreurs est désactivé : le code a planté avant de produire le moindre HTML, et WordPress masque le message d’erreur pour éviter de divulguer aux visiteurs des chemins de fichiers et des détails sur le serveur.

Vous mettez à jour un plugin, vous rechargez le site, et vous obtenez une page blanche sur le front-end, souvent aussi dans wp-admin. Aucune erreur, aucune trace d’appels, rien sur quoi cliquer. La tentation est de commencer à désactiver des éléments au hasard, mais le message existe déjà ; il ne vous est simplement pas montré. Chacune des étapes ci-dessous fonctionne via SFTP ou le gestionnaire de fichiers de votre hébergeur, et une solution passant par la base de données est proposée pour les hébergeurs qui offrent phpMyAdmin mais pas d’accès aux fichiers.

Qu’est-ce que l’écran blanc de la mort de WordPress ?

Un écran blanc signifie que PHP a rencontré une erreur fatale avant de pouvoir générer la page, et que WordPress supprime délibérément le texte de l’erreur sur les sites en production, car celui-ci peut exposer des chemins, des versions et d’autres éléments internes. Les fichiers et la base de données du site sont intacts ; c’est un composant qui a fait planter la requête.

Avant de toucher à quoi que ce soit, vérifiez la boîte de réception de l’adresse e-mail d’administration. Depuis la version 5.2, WordPress envoie un e-mail à l’administrateur lorsqu’une erreur fatale se produit, en nommant le plugin ou le thème défaillant et en incluant un lien qui active le mode de récupération, un état dans lequel le composant défectueux est mis en pause afin que vous puissiez accéder au tableau de bord et le désactiver. Ce lien contient une clé secrète ; saisir l’URL du mode de récupération à la main ne donne pas accès. Si l’e-mail n’arrive jamais (les filtres anti-spam le bloquent parfois, et il n’est envoyé que lorsque l’erreur survient sur un point d’entrée protégé tel que wp-login.php ou la zone d’administration, et non sur une page front-end ou une tâche cron), poursuivez ci-dessous.

Activez la journalisation, pas l’affichage

Ouvrez wp-config.php via SFTP ou le gestionnaire de fichiers de votre hébergeur et ajoutez ces lignes au-dessus de /* That's all, stop editing! */ :

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );

Rechargez la page défectueuse, puis ouvrez le journal, généralement situé dans wp-content/debug.log. Conformément à la documentation de débogage de WordPress, WP_DEBUG_LOG n’a aucun effet si WP_DEBUG n’est pas à true, et WP_DEBUG_DISPLAY vaut true par défaut, ce qui explique pourquoi l’extrait le passe explicitement à false. N’affichez jamais les erreurs sur la page d’un site en production : chaque visiteur verrait les chemins du serveur et des détails du code. Supprimez ces quatre lignes dès que le site est réparé.

Lisez l’erreur : le chemin désigne le coupable

Le journal vous indique un fichier et un numéro de ligne, et le répertoire présent dans ce chemin vous révèle quel composant a échoué. Une entrée réaliste ressemble à ceci :

PHP Fatal error: Uncaught Error: Call to undefined function acme_slider_init() in /home/example/public_html/wp-content/plugins/acme-slider/includes/display.php:87

Le chemin se situe sous wp-content/plugins/acme-slider/, le plugin Acme Slider est donc la cause, et renommer ce seul dossier répare immédiatement le site. En règle générale :

Si le journal indique plutôt une erreur de mémoire, lisez la section suivante. Ce n’est que si le journal est vide que vous devrez recourir aux étapes de bissection.

Comment corriger une erreur d’épuisement de la mémoire dans WordPress ?

Une erreur commençant par Allowed memory size of X bytes exhausted signifie que PHP a atteint son plafond de mémoire en cours de requête. Augmentez la limite de WordPress dans wp-config.php :

define( 'WP_MEMORY_LIMIT', '256M' );

Par défaut, WordPress fixe WP_MEMORY_LIMIT à 40M sur les sites simples et 64M en multisite, et n’augmente jamais que la limite de PHP, sans jamais l’abaisser. Cette constante ne fonctionne que jusqu’au plafond imposé par votre hébergeur au niveau du serveur ; si 256M ne change rien, la limite provient de l’offre d’hébergement et non du réglage, et il vous faudra demander à l’hébergeur de la relever.

Comment désactiver un plugin défectueux sans accès à wp-admin ?

Si le journal nomme un plugin, renommez uniquement le dossier de ce plugin dans wp-content/plugins/. Si le journal est vide, procédez par bissection : renommez wp-content/plugins en plugins.hold, chargez /wp-admin/plugins.php pour que WordPress marque les plugins manquants comme désactivés, renommez le dossier à son nom d’origine, puis réactivez les plugins un par un, en rechargeant le site après chacun, jusqu’à ce que le site casse. Réactiver chaque plugin à la main est le prix de cette méthode, mais les réglages enregistrés par chacun d’eux restent intacts.

Pas d’accès aux fichiers, mais phpMyAdmin disponible ? Ouvrez la table wp_options (votre préfixe n’est peut-être pas wp_), trouvez la ligne où option_name vaut active_plugins, et copiez ou exportez sa valeur option_value actuelle en lieu sûr. Remplacez ensuite cette valeur par le tableau vide sérialisé a:0:{}, ce qui désactive tous les plugins d’un coup. Restaurez la valeur sauvegardée plus tard si vous avez besoin de la liste d’origine.

Comment désactiver un thème défectueux ?

Si le journal pointe vers wp-content/themes/, renommez uniquement le dossier du thème actif, par exemple mytheme en mytheme.hold. WordPress bascule alors sur un thème par défaut fourni avec le CMS s’il est installé ; si aucun ne l’est, installez-en un d’abord via le gestionnaire de fichiers. Le fautif habituel est functions.php, et le journal vous a déjà indiqué la ligne exacte, souvent une modification récente comportant une erreur de syntaxe. Corrigez cette ligne et redonnez au dossier son nom d’origine.

Toujours blanc ? Caches, permissions et version de PHP

Avant de vous fier au moindre résultat, videz tous les caches : le cache de pages du plugin, tout cache serveur, et celui de votre navigateur. Une page blanche mise en cache peut faire croire qu’un site réparé est toujours cassé, et une page valide en cache peut masquer une erreur bien réelle. Vérifiez ensuite les permissions de fichiers, généralement 755 pour les répertoires et 644 pour les fichiers en hébergement mutualisé, et confirmez votre version de PHP : la version de référence recommandée par WordPress est la 8.3 ou une version plus récente. Un site en 7.4 se chargera toujours, mais cette branche ne reçoit plus de correctifs de sécurité depuis des années.

Trois cas sortent du périmètre de cet article : la restauration depuis une sauvegarde (l’outil de sauvegarde de votre hébergeur, en gardant à l’esprit que vous perdez tout ce qui suit l’instantané), les fichiers du cœur corrompus (recopier un téléchargement WordPress neuf par-dessus tout, sauf wp-content et wp-config.php), et les malwares (suivez la procédure de récupération de site piraté de votre hébergeur).

Conclusion

Une page WordPress blanche est un message d’erreur supprimé, pas un mystère, et la solution la plus rapide consiste toujours à lire ce message plutôt qu’à deviner à l’aveugle. Ajoutez dès maintenant les quatre lignes de débogage à wp-config.php, rechargez une fois, et laissez le chemin indiqué dans wp-content/debug.log vous dire exactement quel dossier renommer.

FAQ

Quelle est la différence entre l'écran blanc de la mort et le message « Une erreur critique est survenue sur ce site » ?

Depuis WordPress 5.2, un gestionnaire d'erreurs fatales intégré intercepte la plupart des erreurs fatales PHP et affiche le message d'erreur critique au lieu d'une page blanche. Un écran entièrement blanc signifie que PHP s'est interrompu avant que ce gestionnaire puisse s'exécuter, généralement à cause d'un épuisement de la mémoire ou d'une erreur très tôt dans le chargement, par exemple à l'intérieur de wp-config.php. Les deux découlent d'erreurs fatales PHP, et les étapes de débogage sont identiques.

Pourquoi wp-content/debug.log est-il vide alors que WP_DEBUG est activé ?

Les causes habituelles sont une erreur qui se déclenche avant que les constantes de débogage ne prennent effet, comme une faute de syntaxe dans wp-config.php lui-même, ou un répertoire wp-content sur lequel le serveur web ne peut pas écrire, ce qui empêche WordPress de créer le fichier. Vérifiez que les constantes se situent au-dessus du commentaire « stop editing », puis demandez à votre hébergeur le journal d'erreurs PHP au niveau du serveur, qui enregistre les erreurs fatales indépendamment des réglages de WordPress.

Pourquoi l'écran blanc apparaît-il sur certaines pages et pas sur d'autres ?

L'erreur fatale se trouve dans du code qui ne s'exécute que sur ces requêtes. Un plantage dans un fichier de template de thème rend le front-end blanc alors que wp-admin continue de fonctionner, car l'administration n'affiche pas les templates du front-end. Un plantage dans du code de plugin réservé à l'administration produit l'inverse. Activez la journalisation de débogage, chargez une page défectueuse, et le chemin de fichier de l'erreur enregistrée identifiera le composant fautif.

Peut-on laisser WP_DEBUG et WP_DEBUG_LOG activés en toute sécurité après avoir réparé le site ?

Non. Le journal se trouve par défaut dans wp-content/debug.log, un chemin prévisible et accessible depuis le web que de nombreux hébergeurs ne bloquent pas : quiconque demande cette URL peut donc lire des chemins de fichiers, des détails d'erreurs et des éléments internes de plugins, et le fichier grossit sans rotation. Supprimez les lignes de débogage de wp-config.php dès que le site fonctionne, ou définissez WP_DEBUG_LOG sur un chemin de fichier personnalisé situé en dehors de la racine web publique.