debug.log

Niveau intermédiaire

Activer WP_DEBUG et lire debug.log sans casser le site en production

Activer le journal de débogage sans montrer les erreurs aux visiteurs, trouver debug.log, et lire une trace PHP pour identifier l'extension fautive.

Un site qui plante sans rien dire est un site qui vous cache la réponse. WordPress la connaît, il refuse simplement de l'afficher, et c'est voulu : montrer une trace PHP à vos visiteurs révélerait vos chemins de fichiers et vos versions logicielles.

Il existe un réglage qui écrit l'erreur dans un fichier au lieu de l'afficher. C'est celui-là qu'il faut, et pas l'autre.

Les trois constantes, et pourquoi la troisième compte

Dans wp-config.php, avant la ligne / C'est tout, ne touchez pas à ce qui suit ! / :

define('WP_DEBUG', true);          // active le mode debug
define('WP_DEBUG_LOG', true);      // écrit dans wp-content/debug.log
define('WP_DEBUG_DISPLAY', false); // n'affiche RIEN aux visiteurs

La troisième est celle que tout le monde oublie, et c'est la plus importante en production. Sans elle, WordPress affiche les erreurs en haut de vos pages, à la vue de vos clients et des moteurs de recherche.

À ne jamais laisser en place. Un debug.log qui tourne des mois grossit sans limite et finit par saturer votre quota d'hébergement. Pire, le fichier est accessible en HTTP sur beaucoup d'installations : n'importe qui peut lire votresite.fr/wp-content/debug.log. Activez, diagnostiquez, désactivez, supprimez le fichier.

Où le fichier apparaît

Dans wp-content/debug.log. Il n'existe pas tant qu'aucune erreur n'est survenue : rechargez la page qui plante, puis regardez.

Si le fichier ne se crée jamais, deux causes habituelles. Soit le dossier wp-content n'est pas accessible en écriture, soit WordPress ne démarre pas du tout, et dans ce cas aucun réglage de WordPress ne peut fonctionner, par définition. Voir alors Page blanche ou erreur critique.

Lire une trace, en pratique

Voici un relevé réel, produit en laboratoire sur une extension incompatible :

[22-Aug-2026 07:19 UTC] PHP Fatal error:  Uncaught Error:
Call to undefined function creebs_lab_fonction_supprimee_par_une_maj()
in /var/www/html/wp-content/mu-plugins/lab-fatal.php:3
Stack trace:
#0 /var/www/html/wp-settings.php(451): include_once()
#1 /var/www/html/wp-config.php(139): require_once('/var/www/html/w...')
#2 /var/www/html/wp-load.php(50): require_once('/var/www/html/w...')
#3 /var/www/html/wp-blog-header.php(13): require_once('/var/www/html/w...')
#4 /var/www/html/index.php(17): require('/var/www/html/w...')
  thrown in /var/www/html/wp-content/mu-plugins/lab-fatal.php on line 3

Trois choses à y lire, dans cet ordre :

1. Fatal error contre Warning contre Notice. Seule la première casse le site. Les deux autres remplissent le fichier de bruit et ne méritent pas votre attention tant que le site répond.
2. Le chemin après in, ici wp-content/mu-plugins/lab-fatal.php. C'est votre coupable. Le dossier vous dit tout de suite s'il s'agit d'une extension (plugins), d'une extension imposée (mu-plugins), d'un thème (themes) ou du cœur (wp-includes, wp-admin).
3. La ligne thrown in, tout en bas. C'est l'endroit exact où ça a cassé, et elle est plus fiable que la première ligne quand l'erreur remonte de plusieurs fichiers.

La pile d'appels au milieu se lit de bas en haut : index.php a appelé wp-blog-header.php, qui a appelé wp-load.php, et ainsi de suite jusqu'au fichier fautif. Elle sert quand le coupable n'est pas évident, pour comprendre qui a déclenché quoi.

Le message dont il faut se méfier

Call to undefined function est le plus fréquent après une mise à jour. Il veut dire qu'une extension appelle une fonction qui n'existe plus, parce que WordPress ou PHP l'a supprimée dans une version récente.

Ce n'est donc pas l'extension qui « est cassée » : c'est votre environnement qui a avancé sans elle. Le correctif n'est pas de réparer le fichier, c'est de mettre l'extension à jour, ou de la remplacer si elle n'est plus maintenue.

Refermer proprement

Une fois le coupable identifié :

define('WP_DEBUG', false);

Puis supprimez wp-content/debug.log. Le fichier ne se vide pas tout seul, et il garde en clair les chemins de votre installation.

Si la trace désigne un fichier du cœur de WordPress plutôt qu'une extension, ne modifiez rien : c'est presque toujours le symptôme d'autre chose, et toucher au cœur vous fera perdre la modification à la prochaine mise à jour. Décrivez-moi la trace, je vous dis ce qu'elle raconte.