Deboguer un site WordPress qui ne charge plus

Credit : Logo officiel

Deboguer un site WordPress qui ne charge plus

Dylan D. — Agent Support Technique Serveur Depannage 1855 mots 10 min de lecture

Déboguer un site WordPress qui ne charge plus

Vendredi 17h53. Mon téléphone vibre : un client e-commerce m'appelle, son site WordPress retourne une erreur 500 sur toutes les pages. Le panier ne fonctionne plus, les ventes sont à l'arrêt. Pas de panique : en quinze ans à dépanner WordPress, j'ai vu la même chose des centaines de fois. Une méthode systématique permet de trouver la cause en moins de 20 minutes dans 95% des cas.

Voici exactement le protocole que j'applique sur Debian 12 avec Nginx, PHP 8.3 et WordPress 6.7. Du log au fichier corrompu, en passant par la base de données, on couvre tout.

Avant de toucher à quoi que ce soit

Deux gestes réflexes :

  1. Sauvegarde : tar -czf /tmp/wp-backup-$(date +%F-%H%M).tar.gz /var/www/monsite.fr et mysqldump -u root -p wordpress_db | gzip > /tmp/wp-db-$(date +%F-%H%M).sql.gz
  2. Mode maintenance côté CDN si vous en avez un (Cloudflare a une page de courtoisie en un clic)

Un debug qui casse une chose en plus, c'est arrivé. La sauvegarde évite de doubler la mise.

Étape 1 : activer le mode debug WordPress

80% des erreurs s'expliquent par les logs. Activez-les dans wp-config.php :

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

Le WP_DEBUG_DISPLAY false est crucial : on n'affiche pas les erreurs aux visiteurs (faille de sécurité), on les écrit dans un fichier.

Le log apparaît dans :

tail -f /var/www/monsite.fr/wp-content/debug.log

Rechargez la page du site. Quelques exemples typiques :

PHP Fatal error: Uncaught Error: Call to undefined function some_function()
  in /var/www/monsite.fr/wp-content/plugins/woocommerce/includes/class.php on line 142

On a déjà 90% de la réponse : un plugin WooCommerce est cassé après une mise à jour.

Pour aller plus loin sur le debug, voir Activer le mode debug WordPress.

Étape 2 : les logs serveur

WordPress ne logue que ce qui s'exécute. Si PHP plante avant même de charger WordPress, le debug.log reste vide. Regardez les logs système.

# Erreurs Nginx
tail -100 /var/log/nginx/error.log

# Erreurs PHP-FPM
tail -100 /var/log/php8.3-fpm.log

# Logs systeme recents
journalctl -u nginx --since "1 hour ago"
journalctl -u php8.3-fpm --since "1 hour ago"

# Memoire et OOM killer
dmesg -T | grep -i "out of memory\|killed process"

Une erreur typique de Nginx :

2026/05/07 14:23:11 [error] 1234#0: *567 FastCGI sent in stderr:
  "PHP message: PHP Fatal error: Allowed memory size of 134217728 bytes exhausted"

Message clair : PHP manque de mémoire. La solution est dans la section dédiée plus bas.

Une autre classique :

connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory)

Là PHP-FPM est planté. systemctl restart php8.3-fpm et c'est reparti.

Pour creuser les logs système, voir Logs Linux : où chercher, comment lire.

Étape 3 : désactiver tous les plugins

Le plugin défaillant est la cause numéro 1 de panne WordPress. Loin devant tout le reste. La méthode propre, avec WP-CLI :

cd /var/www/monsite.fr
sudo -u www-data wp plugin deactivate --all

Testez le site. S'il revient :

sudo -u www-data wp plugin list --status=inactive --field=name | while read plugin; do
  echo "=== Activation de $plugin"
  sudo -u www-data wp plugin activate $plugin
  curl -s -o /dev/null -w "HTTP %{http_code}\n" https://monsite.fr
done

Le plugin qui fait passer le code à 500 est le coupable.

Sans WP-CLI (ou si l'admin est inaccessible)

cd /var/www/monsite.fr/wp-content
mv plugins plugins_disabled
mkdir plugins
chown www-data:www-data plugins

WordPress ne voit plus aucun plugin. Si le site repart, renommez plugins_disabled en plugins et désactivez les plugins un par un dans wp-admin avant de les réactiver.

Pour gérer les plugins en CLI, voir Les commandes WP-CLI essentielles.

Étape 4 : tester avec un thème par défaut

Un thème mal codé peut aussi tout casser, surtout après une mise à jour de WordPress core.

sudo -u www-data wp theme activate twentytwentyfour

Si l'admin est inaccessible, basculez via SQL :

mysql -u wp_user -p wordpress_db

UPDATE wp_options SET option_value='twentytwentyfour' WHERE option_name='stylesheet';
UPDATE wp_options SET option_value='twentytwentyfour' WHERE option_name='template';

Si le site fonctionne, votre thème est cassé. Cherchez dans wp-content/themes/votre-theme/functions.php les modifications récentes.

Étape 5 : vérifier la base de données

Une base corrompue (rare mais ça arrive après un crash disque ou un kill -9 mal placé) :

sudo -u www-data wp db check
sudo -u www-data wp db repair

Vérifiez la connexion :

mysql -u wp_user -p wordpress_db -e "SELECT COUNT(*) FROM wp_options;"

Sortie attendue :

+----------+
| COUNT(*) |
+----------+
|      243 |
+----------+

Si la requête échoue, le problème est dans wp-config.php : mauvais mot de passe, mauvais host, mauvais nom de base. Ou MariaDB est arrêté :

systemctl status mariadb
systemctl restart mariadb

Tables crashed

Message typique :

Error: Table './wordpress_db/wp_options' is marked as crashed and should be repaired

Réparation :

mysqlcheck --auto-repair --optimize wordpress_db -u root -p

Étape 6 : les problèmes classiques

Erreur de mémoire PHP

PHP Fatal error: Allowed memory size of 268435456 bytes exhausted

Dans wp-config.php :

define('WP_MEMORY_LIMIT', '512M');
define('WP_MAX_MEMORY_LIMIT', '1024M');

Dans /etc/php/8.3/fpm/php.ini :

memory_limit = 512M

systemctl restart php8.3-fpm

Boucle de redirection infinie (ERR_TOO_MANY_REDIRECTS)

Presque toujours un mismatch entre siteurl et la configuration HTTPS.

sudo -u www-data wp option get siteurl
sudo -u www-data wp option get home

Si vous obtenez http://monsite.fr alors que vous avez forcé HTTPS, mettez à jour :

sudo -u www-data wp option update siteurl 'https://monsite.fr'
sudo -u www-data wp option update home 'https://monsite.fr'

Vérifiez aussi votre wp-config.php :

define('FORCE_SSL_ADMIN', true);
if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && $_SERVER['HTTP_X_FORWARDED_PROTO'] === 'https') {
    $_SERVER['HTTPS'] = 'on';
}

Ce deuxième bloc est crucial derrière un reverse proxy ou Cloudflare. Sans lui, WordPress voit le trafic comme HTTP et redirige vers HTTPS, qui revient en HTTP via le proxy : boucle infinie.

Voir aussi Résoudre les boucles de redirection SSL Cloudflare.

Permissions cassées

find /var/www/monsite.fr -type d -exec chmod 755 {} \;
find /var/www/monsite.fr -type f -exec chmod 644 {} \;
chown -R www-data:www-data /var/www/monsite.fr
chmod 600 /var/www/monsite.fr/wp-config.php

Le wp-config.php à 600 protège vos credentials base de données.

Pour une vue d'ensemble, voir Permissions Linux : chmod, chown, ACL.

Disque plein

df -h
du -sh /var/www/monsite.fr/wp-content/uploads/
du -sh /var/www/monsite.fr/wp-content/debug.log
du -sh /var/log/

J'ai déjà vu un debug.log à 14 Go chez un client qui avait laissé WP_DEBUG_LOG actif depuis 2 ans avec un plugin verbeux. Le disque plein bloque tout, y compris MariaDB.

truncate -s 0 /var/www/monsite.fr/wp-content/debug.log
logrotate -f /etc/logrotate.d/nginx

Erreur "Briefly unavailable for scheduled maintenance"

WordPress reste bloqué en mode maintenance après une mise à jour interrompue.

rm /var/www/monsite.fr/.maintenance

White Screen Of Death (WSOD)

Page entièrement blanche sans erreur HTTP. Souvent une erreur PHP fatale avec display_errors=Off. Activez le debug (étape 1) pour la voir.

Sinon, suspectez :

Étape 7 : vérifier l'intégrité des fichiers core

Une infection malware peut ajouter du code qui plante WordPress de façon erratique.

sudo -u www-data wp core verify-checksums
sudo -u www-data wp plugin verify-checksums --all

Si des fichiers sont signalés modifiés :

sudo -u www-data wp core download --skip-content --force

Pour creuser, voir Vérifier l'intégrité des fichiers WordPress.

Étape 8 : restaurer une sauvegarde

En dernier recours, si rien ne fonctionne après 30 minutes de diagnostic, restaurez. Mieux vaut un site fonctionnel d'hier qu'un site cassé maintenant.

# Mode maintenance
echo '<?php $upgrading = time(); ?>' > /var/www/monsite.fr/.maintenance

# Restaurer fichiers
cd /var/www
mv monsite.fr monsite.fr.broken
tar -xzf /backups/wp-files-2026-05-06.tar.gz

# Restaurer base
mysql -u root -p wordpress_db < /backups/wp-db-2026-05-06.sql

# Lever le mode maintenance
rm /var/www/monsite.fr/.maintenance

Gardez monsite.fr.broken pendant quelques jours pour analyser à froid ce qui a planté.

Erreurs courantes et leur fix

Error establishing a database connection

Cause : MariaDB ne tourne pas, ou les credentials dans wp-config.php sont faux.

Solution :

systemctl status mariadb
systemctl restart mariadb
mysql -u wp_user -p wordpress_db -e "SELECT 1;"

Vérifiez DB_HOST, DB_USER, DB_PASSWORD, DB_NAME dans wp-config.php.

504 Gateway Timeout

Cause : un script PHP tourne plus longtemps que fastcgi_read_timeout Nginx.

Solution : passez fastcgi_read_timeout 300; dans le vhost et max_execution_time = 300 dans php.ini. Si une requête dépasse, c'est souvent une boucle infinie ou une importation lourde mal gérée.

Cannot modify header information - headers already sent

Cause : un fichier wp-config.php, functions.php ou un plugin a un espace ou un BOM avant <?php.

Solution : ouvrez le fichier en mode binaire (hexdump -C wp-config.php | head -1), supprimez tout ce qui précède <?php. Le BOM UTF-8 est EF BB BF.

404 sur tous les articles, accueil OK

Cause : les permaliens sont cassés (réécriture d'URL non active).

Solution :

sudo -u www-data wp rewrite flush --hard

Vérifiez que votre vhost Nginx a bien try_files $uri $uri/ /index.php?$args;.

Failed to open stream: Permission denied

Cause : un fichier ou dossier appartient à root au lieu de www-data.

Solution :

chown -R www-data:www-data /var/www/monsite.fr

Souvent après une manipulation en root (extraction d'archive, etc.).

Pour aller plus loin

Bonus : créer une checklist d'urgence

J'ai un fichier ~/wp-emergency.md que je sauvegarde sur tous mes serveurs. Vous pouvez vous l'inspirer :

# WordPress emergency checklist

1. Backup files: tar -czf /tmp/wp-backup-$(date +%F-%H%M).tar.gz /var/www/SITE
2. Backup DB: mysqldump SITE_db | gzip > /tmp/wp-db-$(date +%F-%H%M).sql.gz
3. Active maintenance Cloudflare
4. Activer WP_DEBUG dans wp-config.php
5. tail -f wp-content/debug.log
6. tail -100 /var/log/nginx/error.log
7. tail -100 /var/log/php8.3-fpm.log
8. wp plugin deactivate --all
9. wp theme activate twentytwentyfour
10. wp db check && wp db repair
11. wp core verify-checksums
12. Restore last backup if all else fails

Ce simple ordre suivi méthodiquement résout 95% des cas. Et le 5% restant ? C'est en général un problème serveur (RAM saturée, disque plein, OOM killer), pas WordPress lui-même.

La méthode bat la panique

Devant un site WordPress mort, ce qui sépare l'amateur du pro, ce n'est pas la connaissance technique : c'est la méthode. Logs WordPress, logs serveur, plugins off, thème par défaut, base de données. Dans cet ordre. À chaque étape, vous éliminez une cause possible. Et si à 18h30 vous n'avez toujours pas trouvé, vous restaurez la sauvegarde et vous analysez à froid le lendemain. Le client préfère mille fois un site fonctionnel d'hier soir à un site cassé pendant le week-end.

# Articles similaires

Sur les memes sujets et plus loin