Déboguer WordPress comme un pro : logs, WP_DEBUG, Query Monitor et WP-CLI

Ton site te lâche au pire moment ? Rassure-toi : avec une méthode claire et les bons outils, tu peux transformer n’importe quelle erreur WordPress en simple incident de parcours. Dans ce guide, tu vas apprendre à debug WordPress comme un pro, pas à pas. On va activer et exploiter WP_DEBUG, interpréter les logs WordPress, naviguer avec Query Monitor et accélérer le diagnostic via WP-CLI. Objectif : réduire le temps entre « ça casse » et « c’est réparé », sans casser autre chose au passage. Tu trouveras aussi une check-list d’actions rapides, des snippets prêts à copier et un cas pratique. Que tu sois freelance, responsable d’un site vitrine ou e-commerçant, ce mode opératoire t’aidera à éclairer chaque erreur WordPress diagnostic de façon fiable.

Dans les 200 premières minutes d’un incident, la pire perte de temps vient souvent de l’approximation : on tente un peu tout au hasard. Ici, on structure. D’abord, on reproduit, on log, on observe. Ensuite, on isole la cause par élimination. Enfin, on corrige, on teste, on sécurise. Tu vas passer naturellement d’indice en indice avec WP_DEBUG, Query Monitor, WP-CLI et les logs WordPress, pour localiser la source du problème (plugin, thème, PHP, base de données, serveur, cache, API externe…).

Méthode de diagnostic WordPress : du symptôme au correctif

1) Prépare un environnement sûr (sauvegarde + staging)

Avant tout, sécurise. Fais une sauvegarde complète (fichiers + base de données) et, si possible, crée un environnement de staging. Cela te permet de tester sans risquer la production. Si le site est totalement hors ligne (erreur 500, écran blanc), télécharge les fichiers par SFTP et exporte la base depuis l’hébergeur. Chez WP Builders, on commence toujours par un snapshot et un plan de retour arrière : c’est ton filet de sécurité.

2) Reproduis l’erreur de manière fiable

Prends 2 minutes pour décrire précisément la séquence qui mène au bug : URL, action cliquée, rôle utilisateur, navigateur, si connecté ou non, etc. Plus tu es précis, plus les logs correspondront à la bonne fenêtre temporelle. Combine ce protocole avec un horodatage (heure exacte) : tu corrèleras les entrées de logs à la seconde près.

3) Isole la zone suspecte

• Front, admin, AJAX, REST, CRON, CLI : quel canal est touché ?
• Événement déclencheur : mise à jour récente, nouveau plugin, changement de thème, import de données, pic de trafic ?
• Étendue : régression globale, page unique, action précise (paiement, upload, formulaire) ?

Ces indices guideront le choix des outils (logs, Query Monitor, WP-CLI) et le périmètre des tests.

Activer WP_DEBUG et lire les logs WordPress

WordPress sait parler. Il suffit d’écouter. Active le mode debug via wp-config.php pour collecter des traces exploitables et silencieuses côté front.

// wp-config.phpdefine('WP_DEBUG', true);define('WP_DEBUG_LOG', true);define('WP_DEBUG_DISPLAY', false);@ini_set('display_errors', 0);// Optionnel en phase d’enquête frontdefine('SCRIPT_DEBUG', true);

Ces constantes activent l’écriture dans wp-content/debug.log sans afficher d’erreurs aux visiteurs. Tu obtiens un journal unifié des avis, warnings, notices et fatals liés à WordPress, aux plugins et au thème.

Pour aller plus loin (bonnes pratiques officielles) : Guide officiel « Debugging in WordPress ».

Comment lire un debug.log comme un pro

Chaque ligne du log contient l’horodatage, le niveau (NOTICE, WARNING, ERROR), le message et souvent la pile d’appel (stack trace). Cherche d’abord les « Fatal error », « Uncaught Exception » ou « PHP Parse error ». Exemple de lecture :

[20-Jan-2025 10:14:53 UTC] PHP Fatal error:  Uncaught Error: Call to undefined function my_plugin\do_magic() in /wp-content/plugins/my-plugin/inc/hooks.php:42Stack trace:#0 /wp-includes/class-wp-hook.php(310): my_plugin\init()#1 /wp-includes/class-wp-hook.php(334): WP_Hook->apply_filters()#2 /wp-includes/plugin.php(517): WP_Hook->do_action()#3 /wp-settings.php(632): do_action('init')

Tu identifies ici le fichier fautif, la ligne, le hook et le plugin. Poursuis avec un test ciblé (désactivation du plugin, patch temporaire, rollback). Si le log grossit trop vite, vide-le entre deux tests pour garder une lecture claire.

Ne pas oublier les logs serveur

PHP-FPM, Apache/Nginx possèdent leurs propres journaux (error.log, access.log). Une erreur 500 « silencieuse » côté WordPress peut être explicite dans le log serveur (limite mémoire, extension PHP manquante, timeout FastCGI). Note l’heure précise, puis corrèle.

• cPanel/Plesk : section « Errors », « Logs »
• SSH : tail -f /var/log/php*/error.log, journalctl -u php-fpm -f, tail -f /var/log/nginx/error.log ou /var/log/apache2/error.log

Pense à repasser WP_DEBUG à false en fin d’intervention sur un site en production, ou conserve uniquement WP_DEBUG_LOG avec rotation.

Query Monitor : le rayon X de WordPress

Query Monitor fournit une vision en temps réel des requêtes SQL, hooks, erreurs PHP, requêtes HTTP, AJAX, REST, scripts et styles. C’est l’outil parfait pour investiguer une page lente, une requête gourmande ou une notice qui pollue.

Installe-le, recharge la page fautive, puis ouvre le panneau depuis la barre d’admin. Filtre par composant (plugin/thème), isole les requêtes dépassant 100 ms, observe les appels HTTP et les erreurs de réponse, et inspecte les hooks déclenchés au moment du bug. Tu peux aussi voir les Capability Checks pour des 403 inattendus.

Référence du plugin : Query Monitor sur WordPress.org.

Cas d’usage rapides avec Query Monitor

• Page très lente : onglet DB Queries → tri par durée → note le groupe (plugin) → corrige l’index ou revois la requête.
• Erreur PHP furtive : onglet PHP Errors → clique sur l’entrée → ouvre le fichier à la ligne incriminée.
• Appels externes : onglet HTTP API Calls → identifie un API lent ou en échec (timeout, 500, 401).
• Conflit de scripts : onglets Scripts/Styles → repère les doublons, versions incompatibles, ou un enqueue mal conditionné.

WP-CLI : diagnostiquer et réparer plus vite depuis le terminal

WP-CLI est la boîte à outils en ligne de commande pour WordPress. Idéal quand l’admin est inaccessible ou pour automatiser des tests. Il permet d’inventorier, d’activer/désactiver, de purger et de vérifier l’intégrité en quelques secondes.

Commandes de base pour une enquête express :

# Vérifier l’intégrité du corewp core verify-checksums# Lister l’état des plugins et des thèmeswp plugin statuswp theme list# Désactiver tous les plugins d’un coup (puis réactiver progressivement)wp plugin deactivate --all# Réactiver un plugin clé pour l’enquêtewp plugin activate query-monitor# Purger caches (selon configuration)wp cache flushwp transient delete --all# Recréer les permaliens (utile pour 404, CPT, redirections bizarres)wp rewrite flush --hard# Vérifier options sensibleswp option get homewp option get siteurl# Examiner la planificationwp cron event list

Astuce : combine --debug pour des traces supplémentaires côté WP-CLI et redirige la sortie vers un fichier pour l’archiver (wp plugin status > audit-plugins.txt).

Logs serveur et erreurs 500 : ce que WordPress ne dit pas

Quand tout est « blanc » côté WordPress, le serveur parle. Une erreur 500 peut venir d’une extension PHP manquante (ex : ext-intl), d’un memory_limit trop bas, d’un max_execution_time atteint ou d’une directive .htaccess invalide. Inspecte les logs PHP-FPM/Apache/Nginx, puis ajuste :

• Mémoire : define('WP_MEMORY_LIMIT', '256M'); (ou côté PHP ini)
• Temps d’exécution : set_time_limit(120); si autorisé
• Modules PHP : active les extensions requises par tes plugins (intl, gd, mbstring, curl, imagick)
• .htaccess : restaure la version standard de WordPress puis regénère les permaliens

Check-list par symptôme : aller droit au but

Écran blanc / Fatal Error

• Activer WP_DEBUG_LOG et consulter debug.log
• Désactiver tous les plugins via WP-CLI, réactiver un par un
• Basculer temporairement sur un thème par défaut (Twenty Twenty-…)
• Vérifier versions PHP et extensions

Erreur 500

• Logs serveur (PHP-FPM/Apache/Nginx)
• Augmenter mémoire et temps d’exécution si besoin
• Regénérer permaliens, vérifier .htaccess
• Core checksums : wp core verify-checksums

Site soudainement lent

• Query Monitor → requêtes > 100 ms, appels HTTP lents
• Purger caches (page, objet, CDN) et transients
• Profiler les hooks lors de l’action lente

Boucle de redirection / 404 inattendues

• wp option get home vs siteurl (incohérence https/http)
• Regénérer permaliens
• Conflit plugin de redirection / sécurité

Erreurs AJAX/REST

• Query Monitor → onglet REST/AJAX
• Console navigateur (réponses 401/403/500)
• Nonce expiré, CORS, mod_security

Cas pratique guidé : l’admin casse après une mise à jour

Scénario : après la mise à jour de 3 plugins, l’administration renvoie une erreur 500 sur « Outils » et « Réglages ». Le front reste en ligne.

1. Reproduire : connecte-toi en tant qu’admin, ouvre « Réglages → Permaliens » → 500. Note l’heure : 14:22:10.
2. Logs WordPress : ouvre wp-content/debug.log → tu trouves un Fatal error lié à /plugins/seo-booster/admin/pages.php:112.
3. WP-CLI : wp plugin deactivate seo-booster → la page se charge à nouveau. Confirmation : wp plugin status montre le plugin désactivé.
4. Query Monitor : réactive le plugin sur staging, recharge « Réglages » → onglet PHP Errors affiche le même fatal, et l’onglet Scripts révèle une dépendance manquante.
5. Correctif : rollback du plugin à la version précédente (ou patch côté plugin si accessible), purge des caches, test de régression, puis mise en production.

Résultat : incident résolu en 12 minutes, cause identifiée, preuves dans les logs et dans un rapport clair pour le client. C’est exactement la démarche que notre équipe applique au quotidien chez WP Builders.

Besoin d’un dépannage WordPress rapide ?

Un bug critique, une erreur 500 ou un site figé ? Nos experts interviennent en moins de 2 heures, diagnostic et réparation inclus.

Je veux une remise en ligne express

Bonnes pratiques pour éviter la récidive

• Journalisation maîtrisée : laisse WP_DEBUG_LOG actif en production si nécessaire, mais avec rotation et accès limité.
• Staging systématique : toute mise à jour majeure se teste d’abord hors production.
• Vérification de compatibilité : versions PHP, MySQL/MariaDB et extensions adaptées au stack visé.
• Monitoring : uptime, erreurs PHP, lenteurs, CRON bloqués : sois alerté avant tes visiteurs.
• Politique d’extensions : moins et mieux. Évite les doublons fonctionnels et les plugins abandonnés.
• Backups fiables : quotidien + pré-mise à jour + restauration testée.

Cheat sheet WP_DEBUG, logs, Query Monitor et WP-CLI

Constantes de débogage

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

Fichiers de logs (selon hébergeur)

• wp-content/debug.log (WordPress)
• /var/log/php*/error.log (PHP)
• /var/log/nginx/error.log ou /var/log/apache2/error.log (Web)

WP-CLI utile au quotidien

wp core verify-checksumswp plugin statuswp plugin deactivate --allwp cache flushwp transient delete --allwp rewrite flush --hardwp option get homewp cron event list

Quand escalader à un expert

• Échecs répétés malgré logs/CLI
• Conflits multisites, e-commerce critique, paiement en échec
• Site hacké ou suspicions de backdoors
• Régressions de performance majeures

Dans ces cas, gagner 2 heures peut sauver une journée de ventes. Notre équipe intervient en urgence, documente le diagnostic et sécurise le correctif pour éviter le retour du bug.

Ressources complémentaires

• Debugging in WordPress (documentation officielle)
• Query Monitor (plugin officiel)

Déboguer WordPress comme un pro, c’est surtout une question de méthode. Tu sais maintenant par où commencer, quels outils activer et comment lire les indices. Et si tu veux déléguer ou gagner un temps précieux, tu sais aussi vers qui te tourner.