Activer le journal de débogage WordPress (mode debug WordPress)

Quand ton site WordPress affiche une page blanche ou une erreur 500, WordPress supprime le message d’erreur qui permettrait d’identifier immédiatement la cause. Activer le journal de débogage WordPress demande à WordPress d’écrire chaque erreur PHP, avertissement et notice dans un fichier — wp-content/debug.log — afin que tu puisses voir exactement quel Plugin, Theme ou quelle ligne de code est responsable.

En résumé : Ajoute ces trois constantes dans wp-config.php, juste au-dessus de la ligne /* That's all, stop editing! Happy publishing. */ — define( 'WP_DEBUG', true );, define( 'WP_DEBUG_LOG', true ); et define( 'WP_DEBUG_DISPLAY', false );. Après avoir enregistré, recharge la page et WordPress écrit toutes les erreurs PHP dans wp-content/debug.log. Une fois le débogage terminé, désactive le mode debug WordPress avant de déployer en production.

Mode debug WordPress selon l’environnement d’hébergement

La façon dont tu accèdes à wp-config.php — et l’endroit où se retrouve debug.log — dépend de ton environnement d’hébergement. Utilise la section qui correspond à ta configuration.

Hébergement mutualisé (cPanel / FTP)

Sur les hébergements mutualisés comme Bluehost, SiteGround ou Hostinger, wp-config.php se trouve dans le répertoire racine de WordPress, généralement public_html/. Modifie-le via le Gestionnaire de fichiers de cPanel ou un client FTP comme FileZilla.

Problème de droits courant : si WordPress ne peut pas écrire debug.log, le répertoire wp-content/ doit être accessible en écriture par le serveur web. La permission standard est 755 pour les répertoires. Ne la mets pas à 777 sur un hébergement mutualisé — cela rend le répertoire accessible en écriture par tout le monde, ce qui représente un risque de sécurité.

D’après les tickets de support WP STAGING, l’hébergement mutualisé est l’endroit où debug.log échoue le plus souvent silencieusement, car de nombreux hébergements mutualisés capturent les erreurs PHP dans leur propre journal côté serveur plutôt que de laisser WordPress créer debug.log. Si le fichier n’apparaît jamais après avoir activé WP_DEBUG, demande à ton hébergeur où se trouve son journal d’erreurs PHP.

VPS / Serveur dédié (SSH)

Avec un accès SSH, modifie wp-config.php directement depuis la ligne de commande :

nano /var/www/html/wp-config.php

Après avoir enregistré, surveille le journal en temps réel pour voir les erreurs au fur et à mesure :

tail -f /var/www/html/wp-content/debug.log

Si debug.log n’est pas créé, vérifie que le répertoire wp-content/ appartient à l’utilisateur du serveur web (www-data sur Ubuntu/Debian, apache ou nginx sur CentOS/AlmaLinux) :

ls -la /var/www/html/wp-content/
chown www-data:www-data /var/www/html/wp-content/

Développement local (LocalWP / DevKinsta / XAMPP)

debug.log se trouve au même emplacement wp-content/debug.log, mais le chemin de base dépend de ton environnement local :

• LocalWP : ~/Local Sites/<site-name>/app/public/wp-content/debug.log
• DevKinsta : ~/DevKinsta/projects/<site-name>/app/public/wp-content/debug.log
• XAMPP sur Windows : C:xampphtdocs<site-name>wp-contentdebug.log

Les environnements locaux ont rarement des problèmes de droits car le serveur web et ton compte utilisateur fonctionnent en tant que même processus. Si debug.log n’apparaît jamais, vérifie que ton wp-config.php se trouve bien à la racine de WordPress et non dans un répertoire parent.

Site de staging WP STAGING

D’après nos tests avec WP STAGING, activer le mode debug sur le clone de staging est l’approche la plus sûre — le clone est une copie exacte du site live, donc toute erreur reproduite correspondra à l’environnement live sans affecter les vrais visiteurs.

Pour activer le mode debug sur ton site de staging, modifie le wp-config.php dans le répertoire de staging. WP STAGING crée le site de staging dans un sous-répertoire ou sous-domaine séparé avec son propre wp-config.php, donc les modifications là-bas n’affectent pas le paramètre WP_DEBUG du site live.

Si tu ne peux pas te connecter à ton site de staging, le journal de débogage est le premier endroit à vérifier — les échecs de connexion sur le staging sont le plus souvent des erreurs fatales PHP qui n’apparaissent que dans le journal.

Comment activer le mode debug de WordPress

Tu peux activer le « mode debug » de WordPress en modifiant quelques lignes dans le fichier wp-config.php de ton installation WordPress :

1. Connecte-toi à cPanel ou à ton site via FTP
2. Utilise le Gestionnaire de fichiers cPanel ou ton client FTP et modifie le fichier wp-config.php
3. Copie les lignes ci-dessous dans le fichier wp-config.php ou, si elles existent déjà, modifie leurs valeurs en true :

define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );

Attention : Assure-toi de copier les lignes exactement telles qu’elles sont affichées, sans oublier un point-virgule ou d’autres caractères !

1. Colle les lignes copiées juste au-dessus de la ligne qui indique
   /* That's all, stop editing! Happy publishing. */

Après avoir rechargé le site, WordPress écrira toutes les erreurs PHP dans le fichier debug.log.
WordPress enregistre ce fichier dans le dossier : wp-content/debug.log

Afficher les erreurs sur le frontend WordPress

Si tu veux voir les erreurs du journal de débogage directement à l’écran plutôt qu’en activant le fichier debug.log, modifie la ligne qui indique define( 'WP_DEBUG_DISPLAY', false );

Renomme-la en : define( 'WP_DEBUG_DISPLAY', true );.

WordPress ne crée pas le fichier journal debug.log

Certains hébergeurs[1] n’autorisent pas la création du fichier WordPress debug.log. Ils capturent toutes les erreurs PHP et laissent WordPress les écrire dans un fichier journal séparé.

Si WordPress ne peut pas créer debug.log, suis cet arbre de décision pour trouver la cause :

1. Cherche un fichier journal alternatif. Vérifie la racine du site pour un fichier nommé error_log, ou cherche un dossier /logs/. De nombreux hébergements mutualisés, dont HostGator, redirigent les erreurs PHP vers leur propre journal côté serveur au lieu de laisser WordPress écrire debug.log. Si tu ne trouves aucun fichier journal, demande à ton hébergeur où il stocke les journaux d’erreurs PHP.

2. Vérifie les droits du répertoire. wp-content/ doit être accessible en écriture par le serveur web. Sur un serveur avec accès SSH, exécute :

ls -la /path/to/wp-content/

Le répertoire doit appartenir à www-data (Ubuntu/Debian) ou apache (CentOS). La permission standard est 755. Si le répertoire appartient à root et que l’utilisateur du serveur web ne peut pas y écrire, debug.log échouera silencieusement à être créé.

3. Vérifie si display_errors écrase tes paramètres. Certaines configurations php.ini serveur ou directives .htaccess définissent php_flag display_errors Off, ce qui peut supprimer la sortie même lorsque WP_DEBUG_DISPLAY est true. Vérifie les paramètres PHP de ton panneau de contrôle d’hébergement ou contacte ton hébergeur.

4. Vérifie si un must-use plugin supprime les erreurs. Les fichiers dans wp-content/mu-plugins/ se chargent avant tout le reste et peuvent remplacer les gestionnaires d’erreurs de WordPress. Si ton hébergeur a installé un must-use plugin qui intercepte les erreurs, cela peut empêcher debug.log d’être écrit. Inspecte les fichiers dans wp-content/mu-plugins/ si ce répertoire existe.

5. Vérifie le niveau error_reporting. Si error_reporting est défini de façon trop restrictive — par exemple, seulement sur E_ERROR — PHP ne journalisera pas les avertissements et notices. WordPress définit error_reporting(E_ALL) lorsque WP_DEBUG est true, mais un Plugin ou la configuration du serveur peut modifier cela après le chargement de WordPress. Consulte la documentation PHP sur error_reporting pour la liste complète des constantes et ce que chaque niveau couvre.

6. Vérifie que le répertoire du chemin de journalisation existe. Si tu as déjà défini WP_DEBUG_LOG sur un chemin personnalisé, confirme que le répertoire à ce chemin existe et est accessible en écriture par le serveur web.

Sinon, tu peux utiliser la méthode mentionnée ci-dessus et modifier
define( 'WP_DEBUG_DISPLAY', false ); en
define( 'WP_DEBUG_DISPLAY', true );

Si cela fonctionne, tu verras les erreurs concernées sur le frontend. Cela t’aidera à résoudre l’erreur fatale.

Tu trouveras des instructions plus détaillées sur l’activation du mode debug de WordPress dans la documentation de débogage WordPress.

Au moment de la rédaction de cet article : [1] HostGator

Méthode alternative pour déboguer les erreurs fatales quand debug.log n’est pas généré

Parfois, quand tu actives le mode WP_DEBUG pour résoudre une erreur fatale, tu peux constater que ton hébergeur empêche la création du fichier debug.log. Même définir WP_DEBUG_DISPLAY à true n’aide pas toujours à afficher l’erreur sur le frontend.

Si tu es bloqué dans cette situation, voici une solution de contournement qui fonctionne quand rien d’autre ne marche.

Forcer l’affichage des erreurs dans wp-config.php

Ce snippet force l’affichage de l’erreur fatale :

register_shutdown_function(function () {
    $error = error_get_last();
    if ($error) {
        print_r($error);
    }
});

🚨 N’oublie pas de supprimer le snippet après le débogage et utilise-le uniquement quand tu as un accès FTP pour un retour arrière sûr.

Lire le journal de débogage WordPress

Une fois que debug.log existe, ouvre-le dans n’importe quel éditeur de texte. Chaque ligne suit ce modèle :

[DD-Mon-YYYY HH:MM:SS UTC] PHP Fatal error: <message> in /path/to/file.php on line N
[DD-Mon-YYYY HH:MM:SS UTC] PHP Warning: <message> in /path/to/file.php on line N
[DD-Mon-YYYY HH:MM:SS UTC] PHP Notice: <message> in /path/to/file.php on line N

Voici ce que signifie chaque classe d’erreur et quand agir :

PHP Fatal error — PHP a cessé de s’exécuter. C’est toujours la cause d’une page blanche ou d’une erreur 500. Le chemin de fichier et le numéro de ligne dans l’entrée du journal te montrent exactement où chercher. Trouve le Plugin ou Theme dont le fichier est mentionné dans l’entrée et désactive-le pour confirmer.

PHP Warning — PHP a rencontré quelque chose d’inattendu mais a continué à s’exécuter. Les avertissements ne causent pas de pages blanches en eux-mêmes, mais ils indiquent souvent un bug qui deviendra une erreur fatale dans des conditions différentes. Si tu actives le journal de débogage WordPress pour identifier les avertissements PHP liés aux limites de configuration PHP, un avertissement max_input_vars d’un Plugin à formulaires multiples est une entrée courante.

PHP Notice — PHP a noté un problème potentiel comme une variable non définie. Les notices indiquent rarement un vrai bug en production, mais si la même notice apparaît des milliers de fois par chargement de page, cela peut signaler un problème de boucle ou de récursion qui dégrade les performances.

Erreurs de base de données $wpdb — Les lignes commençant par WordPress database error indiquent qu’une requête a échoué. Elles pointent généralement vers un Plugin générant une requête SQL malformée ou un problème dans les tables de la base de données WordPress que la requête cible. Le message d’erreur inclut la requête qui a échoué, ce qui permet d’identifier facilement le Plugin responsable.

Quand tu trouves une erreur fatale ou un avertissement répété, regarde le chemin de fichier dans l’entrée du journal. S’il appartient à un Plugin ou Theme, désactive-le, recharge la page et confirme que les entrées du journal s’arrêtent.

Si le journal de débogage révèle des erreurs REST API dans WordPress, l’entrée du journal nomme généralement la fonction exacte qui a échoué — suis le guide dédié à partir de ce point de départ. S’il révèle des erreurs ERR_CONNECTION_REFUSED, elles proviennent de la couche serveur ou réseau plutôt que de PHP. Pour les erreurs 414 Request-URI Too Large, le journal identifie généralement quel Plugin génère l’URL surdimensionnée.

Modifier l’emplacement du fichier debug.log

Tu peux modifier le chemin que WordPress utilise pour la journalisation des erreurs en changeant la valeur de la constante WP_DEBUG_LOG.

Ouvre wp-config.php et trouve la ligne contenant WP_DEBUG_LOG.

Recherche : define( 'WP_DEBUG_LOG', true );

Remplace par : define( 'WP_DEBUG_LOG', '/logs/errors.log' );

Cela permet à WordPress d’écrire les messages d’erreur dans un chemin de fichier différent.

Comme chemin de destination, tu peux aussi utiliser /dev/stderr ou /dev/stdout. C’est utile dans Docker ou d’autres environnements conteneurisés où tu veux tous les journaux dans un flux de sortie partagé.

Désactiver le mode debug de WordPress après le débogage

Une fois que tu as terminé d’investiguer, désactive immédiatement le mode debug. Le fichier debug.log est accessible depuis le web par défaut à wp-content/debug.log, et il peut contenir des détails d’erreurs de base de données, des chemins de fichiers et d’autres informations serveur qui ne devraient pas être lisibles publiquement.

Supprime le fichier debug.log et désactive la journalisation des erreurs en remettant define( 'WP_DEBUG', true ); à define( 'WP_DEBUG', false );.

Pense toujours à désactiver le mode debug de WordPress avant de déployer en production quand tu travailles sur un site de staging. Le flux de déploiement de WP STAGING est le bon point de contrôle pour confirmer que WP_DEBUG est désactivé avant que le clone n’écrase le site live.

Articles connexes

• Page blanche sur un site de staging WordPress
• Comment corriger une erreur 500 et une page blanche WordPress
• Comment déboguer les erreurs JavaScript dans la console du navigateur