Debug WordPress : le guide complet pour diagnostiquer et corriger les erreurs

Pourquoi votre site WordPress vous cache ses erreurs

Votre site affiche une page blanche. Pas de message, pas d'indice, rien. Juste du blanc.

Normal. WordPress désactive l'affichage des erreurs PHP par défaut. C'est un choix de sécurité : un visiteur n'a pas besoin de voir que votre plugin de formulaire provoque un " Fatal Error " à la ligne 247. Mais pour vous, administrateur du site, cette censure devient un problème quand il faut diagnostiquer une panne.

Le mode debug, c'est le voyant moteur de votre voiture WordPress. Il ne répare rien. Il vous dit où chercher.

Formateur WordPress depuis 2012, fondateur de WPServeur, co-créateur de WPS Hide Login (2 millions d’installations actives) et enseignant à Pôle Sup Nîmes, j’ai vu 300+ stagiaires bloqués devant un écran blanc sans savoir par où commencer. La réponse est toujours la même : on active le debug, on lit le log, on trouve le coupable. En 5 minutes, le mystère est résolu. Si tu n’es même pas sûr du thème ou des plugins qui tournent sur le site en panne, commence par lancer un Détecteur WordPress : ça te donne la stack complète en 3 secondes, sans aucun accès admin.

Quand est-ce que le debug te sauve la mise ? Trois situations classiques :

• Page blanche (WSOD) – le site ne répond plus après une mise à jour
• Erreur 500 – le serveur plante sans explication visible
• Plugin défaillant – un conflit casse une fonctionnalité sans tout faire tomber

Les 4 constantes de debug dans wp-config.php

Tout se joue dans un seul fichier : wp-config.php, à la racine de votre installation WordPress. Quatre constantes PHP contrôlent le comportement du debug. Elles travaillent ensemble.

WP_DEBUG – l'interrupteur principal

C'est le bouton ON/OFF. Par défaut, il est sur false. Quand vous le passez à true, WordPress affiche toutes les erreurs PHP : fatales, warnings, notices, fonctions dépréciées. Tout remonte à la surface.

define( 'WP_DEBUG', true );

WP_DEBUG_LOG – écrire au lieu d'afficher

Afficher les erreurs à l'écran, c'est pratique en local. Sur un site en ligne… c'est une catastrophe ! WP_DEBUG_LOG enregistre toutes les erreurs dans un fichier /wp-content/debug.log au lieu de les balancer dans le HTML de vos pages.

define( 'WP_DEBUG_LOG', true );

Tu peux aussi spécifier un chemin personnalisé :

define( 'WP_DEBUG_LOG', '/home/user/logs/wp-debug.log' );

WP_DEBUG_DISPLAY – masquer les erreurs aux visiteurs

Cette constante contrôle si les erreurs s'affichent visuellement sur vos pages. Sur un site en production, mettez-la toujours sur false. Les erreurs iront dans le fichier log, pas dans le navigateur de vos visiteurs.

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

SCRIPT_DEBUG – déboguer les fichiers JS et CSS

Par défaut, WordPress charge les versions minifiées (.min.js, .min.css) de ses scripts. SCRIPT_DEBUG force le chargement des versions complètes, lisibles. Indispensable quand vous suspectez un conflit JavaScript entre deux plugins.

define( 'SCRIPT_DEBUG', true );

Mon conseil : ne l'active que pour déboguer un problème JS/CSS précis. Ça ralentit le chargement (comptez +15-20% de temps de rendu sur les pages lourdes en scripts).

La configuration optimale pour un site en production

Voici le bloc que j'utilise systématiquement en formation quand un stagiaire doit diagnostiquer un problème sur un site en ligne :

/* === MODE DEBUG (temporaire) === */
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );
define( 'WP_DEBUG_DISPLAY', false );
@ini_set( 'display_errors', 0 );
define( 'SCRIPT_DEBUG', false );
/* === FIN DEBUG === */

Les erreurs s'enregistrent dans le fichier log. Rien ne s'affiche à l'écran. Le site reste utilisable pendant le diagnostic.

Activer le debug pas à pas – 3 méthodes

La plupart des tutoriels se limitent à une seule méthode. Vous en avez trois, selon votre niveau et vos outils.

Méthode 1 – Via FTP ou le gestionnaire de fichiers (la classique)

C'est la méthode universelle. Elle fonctionne avec n'importe quel hébergeur.

1. Sauvegardez votre fichier wp-config.php actuel (téléchargez-le sur votre ordinateur)
2. Connectez-vous en FTP (FileZilla, Cyberduck) ou via le gestionnaire de fichiers de votre hébergeur (cPanel chez O2switch, hPanel chez Hostinger)
3. Ouvrez wp-config.php à la racine du site
4. Cherchez la ligne

   define( 'WP_DEBUG', false );

5. Remplacez-la par le bloc de 6 lignes ci-dessus
6. Enregistrez et renvoyez le fichier sur le serveur

Le code doit être placé avant la ligne /* That's all, stop editing! */.

Méthode 2 – Via WP-CLI (la rapide)

Si vous avez un accès SSH à votre serveur (ou un environnement local avec WP-CLI installé), c'est la méthode la plus rapide. Deux commandes suffisent :

wp config set WP_DEBUG true --raw
wp config set WP_DEBUG_LOG true --raw
wp config set WP_DEBUG_DISPLAY false --raw

Le flag --raw est important : sans lui, WP-CLI écrirait 'true' (chaîne de caractères) au lieu de true (booléen PHP). Et define('WP_DEBUG', 'true') avec des guillemets, ça active le debug – mais pas pour les bonnes raisons.

Pour désactiver après diagnostic :

wp config set WP_DEBUG false --raw

C'est la méthode que j'utilise au quotidien depuis des années… et pourtant, elle est rarement documentée dans les guides francophones.

Méthode 3 – Via le plugin WP Debugging (la sûre)

Pour ceux qui ne veulent pas toucher au code, ce plugin fait tout le travail. Tu l'actives, le debug s'allume. Tu le désactives, il remet tout en place. Zéro risque d'oublier une constante à true en production !

WP Debugging – v2.12.2 – ⭐ 5/5 (19 avis) – 10 000+ installations – Télécharger sur WordPress.org

Le plugin d'Andy Fragen active automatiquement WP_DEBUG, WP_DEBUG_LOG, SCRIPT_DEBUG et SAVEQUERIES. Il désactive WP_DEBUG_DISPLAY. Bref, il fait exactement ce qu'il faut sans que tu aies à y penser.

Lire et comprendre le fichier debug.log

Le debug est activé. Et maintenant, on fait quoi ? Il faut lire ce qu'il raconte.

Où trouver le fichier

Par défaut : /wp-content/debug.log. Connecte-toi en FTP, navigue dans le dossier wp-content, le fichier est là. Si tu as configuré un chemin personnalisé avec WP_DEBUG_LOG, va directement voir.

Avec WP-CLI, c'est encore plus simple :

tail -f wp-content/debug.log

Cette commande affiche les erreurs en temps réel au fur et à mesure qu'elles arrivent. Recharge la page problématique dans un autre onglet et observe… c'est presque hypnotisant.

Anatomie d'une ligne d'erreur

Une erreur PHP dans le debug.log ressemble à ceci :

[06-Mar-2026 14:30:00 UTC] PHP Fatal error: Uncaught Error: Call to undefined function custom_function() in /home/user/public_html/wp-content/plugins/mon-plugin/includes/class-main.php on line 127

Décryptons :

• [06-Mar-2026 14:30:00 UTC] : horodatage de l'erreur
• PHP Fatal error : le type (Fatal = le script s'arrête)
• Call to undefined function : la cause (une fonction n'existe pas)
• /wp-content/plugins/mon-plugin/ : le coupable (un plugin)
• on line 127 : la ligne exacte du problème

Les 5 types d'erreurs PHP

Pas de panique, toutes les erreurs ne se valent pas. Voici comment les prioriser :

1. Fatal Error : le site plante. Le script s'arrête net. Priorité maximale. Cause fréquente : plugin incompatible ou mémoire PHP insuffisante.
2. Parse Error : erreur de syntaxe PHP. Une parenthèse manquante, un point-virgule oublié. Le fichier ne peut même pas être lu par PHP.
3. Warning : quelque chose ne va pas, mais le site continue de fonctionner. Souvent une variable vide ou un fichier introuvable. À surveiller.
4. Notice : un détail technique à corriger. Pas urgent, pas visible pour les visiteurs. Typiquement une variable utilisée sans être définie.
5. Deprecated : le code utilise une fonction obsolète. Ça marche encore, mais ça pourrait casser avec la prochaine version de PHP. Signal d'alerte pour mettre à jour le plugin ou le thème concerné.

Sécuriser l'accès au debug.log

Ce fichier contient des chemins serveur, des noms de tables de base de données, parfois des informations sensibles. Par défaut, n'importe qui peut y accéder via votre-site.com/wp-content/debug.log. Un cadeau pour les pirates !

Règle .htaccess à placer dans /wp-content/.htaccess :

<Files debug.log>
  Order allow,deny
  Deny from all
</Files>

Pour Nginx :

location ~* /debug\.log$ {
  deny all;
}

J'ai vu des fichiers debug.log de plusieurs Mo accessibles publiquement sur des sites clients. Avec des chemins serveur complets dedans… un festin pour les pirates.

Query Monitor : le couteau suisse du debug WordPress

Le mode debug natif, c'est bien. Mais ça reste du texte brut dans un fichier log. Tu veux un vrai tableau de bord visuel ? Query Monitor s'intègre directement dans ta barre d'administration WordPress.

Query Monitor – v4.0.6 – ⭐ 4.9/5 (465 avis) – 200 000+ installations – Télécharger sur WordPress.org

Développé par John Blackbourn (contributeur WordPress Core), ce plugin est le standard de l'industrie. Gratuit, léger, sans publicité. La version 4, sortie en avril 2026, a entièrement refait le rendu en Preact et ajouté une vue timeline.

Ce que Query Monitor vous montre

Une fois activé, une barre apparaît en haut de chaque page de ton site (côté admin). Elle affiche en temps réel :

• Erreurs PHP : avec le fichier, la ligne et le contexte
• Requêtes SQL : nombre, temps d'exécution, requêtes lentes surlignées en rouge
• Hooks et filtres : quel plugin s'accroche à quel hook, dans quel ordre
• Appels HTTP : requêtes vers des APIs externes (lentes, échouées)
• Transients : données en cache, expirées ou non
• Mémoire et temps : consommation mémoire PHP, temps de génération de la page

Cas concret : le plugin qui fait 200 requêtes SQL

En formation Qualiopi, j’ai eu un cas révélateur que je raconte encore aux participants de mes sessions WordCamp. Le site d’un stagiaire mettait 8 secondes à charger la page d’accueil. Pas d’erreur PHP, pas de page blanche. Juste une lenteur inexplicable. On cherchait depuis des heures avec du ping, du PageSpeed, du GTmetrix. Rien ne sortait.

On installe Query Monitor. Verdict : 847 requêtes SQL pour afficher la homepage. Un plugin de témoignages exécutait une requête par témoignage, sans cache, à chaque chargement. 200 témoignages = 200 requêtes supplémentaires. Remplacement du plugin, passage à 45 requêtes. Temps de chargement : 1,2 seconde.

Sans Query Monitor, on aurait passé des heures à désactiver les plugins un par un. Là, 2 minutes. CQFD.

Les 10 erreurs que je vois le plus en formation

Depuis 2012, j'ai formé plus de 300 personnes à WordPress via mes sessions Qualiopi. Du débutant complet au développeur confirmé. Certaines erreurs reviennent systématiquement… Voici mon top 10, avec le diagnostic et la solution.

1. Page blanche (WSOD) après une mise à jour

Dans le debug.log : PHP Fatal error: Allowed memory size of 67108864 bytes exhausted. Le plugin mis à jour consomme plus de mémoire. Solution : augmenter WP_MEMORY_LIMIT dans wp-config.php à 256M, ou désactiver le plugin fautif via FTP en renommant son dossier. Avant de tout réactiver, je passe chaque plugin suspect au Vérificateur de Plugins pour repérer les plugins abandonnés ou non maintenus qui explosent après une montée de version PHP.

2. Erreur 500 sans message

Souvent un fichier .htaccess corrompu. Renomme-le en .htaccess-backup via FTP. Si le site revient : va dans Réglages > Permaliens et clique " Enregistrer " pour régénérer un .htaccess propre.

3. " Call to undefined function "

Un plugin appelle une fonction d'un autre plugin qui est désactivé. Dépendance non gérée. Le debug.log pointe directement vers le fichier et la ligne. Réactive le plugin manquant ou retire celui qui cause l'appel.

4. " Allowed memory size exhausted "

WordPress demande plus de RAM que ce que PHP autorise. Ajoute dans wp-config.php :

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

Si ça ne suffit pas, le problème vient d'un plugin gourmand (souvent un page builder ou un plugin d'import). Query Monitor te montrera lequel.

5. " Maximum execution time exceeded "

Le script PHP tourne trop longtemps (défaut : 30 secondes). Fréquent lors des imports WooCommerce ou des migrations. Augmente la limite dans php.ini ou dans wp-config.php via set_time_limit(300).

6. Erreurs Deprecated après un changement de version PHP

Ton hébergeur passe de PHP 7.4 à 8.1. Le debug.log se remplit de Deprecated: Function strftime() is deprecated. C'est le plugin ou le thème qui utilise d'anciennes fonctions PHP. Mets-les à jour, ou contacte le développeur.

7. Conflit jQuery

Deux plugins chargent deux versions différentes de jQuery. Résultat : des boutons ne fonctionnent plus, des sliders disparaissent. Active SCRIPT_DEBUG et regarde la console du navigateur (F12 > Console). Query Monitor montre aussi les scripts chargés et leurs dépendances.

8. " Headers already sent "

L'erreur la plus fourbe ! Un espace ou une ligne vide avant le <?php d'ouverture dans wp-config.php ou dans functions.php. Invisible à l'oeil nu. Ouvre le fichier incriminé dans un éditeur de code (VS Code, Sublime Text) et supprime tout caractère avant <?php.

9. BOM UTF-8

Variante du précédent. Le fichier a été enregistré avec un BOM (Byte Order Mark) invisible. Même symptôme : " Headers already sent ". Solution : réenregistre le fichier en UTF-8 sans BOM dans ton éditeur.

10. Erreurs de l'API REST WordPress

L'éditeur Gutenberg plante ou n'enregistre pas. Le debug.log montre des erreurs liées à rest_api. Causes fréquentes : un plugin de sécurité qui bloque les endpoints REST, un pare-feu trop agressif, ou un fichier .htaccess qui filtre les requêtes wp-json.

Bonnes pratiques et sécurité du debug

Le mode debug est un outil de diagnostic, pas un réglage permanent. Il fait partie de la maintenance WordPress ponctuelle. Le laisser actif en production, c'est comme laisser le capot de ta voiture ouvert sur l'autoroute.

Il faudra respecter quelques règles simples.

• Règle n°1 : désactive après usage. Remets WP_DEBUG à false dès que le diagnostic est terminé. Pas demain. Maintenant.
• Règle n°2 : supprime le fichier debug.log. Ce fichier grossit à chaque erreur. Sur un site avec beaucoup de notices PHP, il peut atteindre plusieurs centaines de Mo en quelques jours. J’ai déjà vu un debug.log de 2 Go qui saturait l’espace disque du serveur… pour une simple notice répétée à chaque chargement de page. Arghhhh.
• Règle n°3 : protège le fichier. Comme expliqué plus haut, bloque l'accès HTTP avec la règle .htaccess ou Nginx.
• Règle n°4 : n’active jamais WP_DEBUG_DISPLAY en production. Afficher des chemins serveur comme /home/dufa8945/public_html/ dans le navigateur, c’est offrir un plan de ton hébergement à un attaquant. J’ai vu un client qui s’était fait pirater trois semaines après avoir laissé cette constante active par erreur… le rapport post-mortem de l’hébergeur pointait directement les chemins exposés dans le code source des pages.

Bonus : SAVEQUERIES. Cette constante enregistre toutes les requêtes SQL dans un tableau PHP ($wpdb->queries). Utile pour identifier les requêtes lentes, surtout combinée avec Query Monitor qui affiche ces données dans son onglet Database. Mais elle ralentit considérablement le site (WordPress Performance Team mesure un overhead de 10-15% sur les pages lourdes). À n'utiliser qu'en local ou en staging, jamais en production.

define( 'SAVEQUERIES', true );

Questions fréquentes sur le debug WordPress

define('WP_DEBUG_LOG', '/chemin/vers/mon-debug.log');

define('WP_DEBUG_DISPLAY', false);

define('WP_DEBUG', true);

define('WP_DEBUG', false);

Le debug WordPress n'est pas réservé aux développeurs. C'est un réflexe de diagnostic que tout administrateur de site devrait avoir dans sa boîte à outils… au même titre que la sauvegarde ou la mise à jour. En formation, je le répète à chaque session : 90% des pannes WordPress se résolvent en lisant le debug.log. Quid de la suite ? Si tu veux aller plus loin dans la maîtrise de ton installation, je te recommande de creuser WP-CLI : les commandes de diagnostic en ligne sont un complément naturel au debug.