Erreur 502 Bad Gateway sur WordPress : trouver la cause et réparer pas à pas 🔧

Le symptôme est toujours le même : à la place de votre site, une page presque vide affiche 502 Bad Gateway, souvent avec le mot nginx en dessous. Si votre site passe par Cloudflare, vous voyez plutôt une page aux couleurs de Cloudflare titrée « Bad gateway », avec la mention « Error code 502 ». Sur un serveur Apache utilisé comme relais, le message est « Proxy Error : The proxy server received an invalid response from an upstream server ».

Ce guide suit notre méthode d’intervention, du test le plus simple au réglage du serveur. Si votre site est à l’arrêt, notre équipe peut aussi prendre la main tout de suite : dépannage WordPress en urgence. La définition courte est dans la fiche 502 de notre décodeur d’erreurs.

Que veut dire « 502 Bad Gateway » sur un site WordPress ?

Le code 502 veut dire qu’un serveur intermédiaire a transmis votre demande au programme qui fabrique les pages et a reçu en retour une réponse vide, coupée ou illisible. Sur la plupart des hébergements actuels, ce programme est PHP-FPM, le gestionnaire qui fait tourner le code PHP de WordPress dans plusieurs processus en parallèle.

Une erreur 504 signifie que PHP a mis trop longtemps à répondre, alors qu’une erreur 503 indique un service volontairement indisponible ou en surcharge. Avec un 502, PHP a répondu de travers ou s’est interrompu en route.

Comment savoir si le 502 vient de Cloudflare, du serveur ou de WordPress ?

Trois observations suffisent en général à situer la panne.

• La page d’erreur porte la marque Cloudflare : selon la documentation de Cloudflare, le 502 vient alors de votre serveur d’origine, pas de Cloudflare. Une page blanche sans marque oriente vers Cloudflare lui-même.
• Tout le site ou une seule action : partout, PHP-FPM est arrêté ou saturé ; pendant un import ou un envoi d’image, une tâche trop lourde ou une extension précise est en cause.
• Permanent ou intermittent : une erreur qui va et vient avec le trafic signe une limite de processus atteinte ; une erreur constante depuis une mise à jour désigne une extension, le thème ou la version de PHP.

Pourquoi WordPress affiche-t-il une erreur 502 ?

Dans l’ordre de ce que nous rencontrons le plus souvent, voici les causes et la façon de les reconnaître.

• PHP-FPM saturé : tous les processus PHP sont occupés, les nouvelles demandes sont rejetées. On le reconnaît au message « server reached pm.max_children setting » dans le journal PHP-FPM.
• Une extension qui fait planter PHP : le processus s’arrête net au milieu de la page. Le journal PHP-FPM indique alors un enfant « exited on signal 11 (SIGSEGV) ».
• PHP-FPM arrêté ou mal redémarré : après un changement de version de PHP dans l’espace d’hébergement, le relais cherche encore l’ancien processus. Le journal nginx affiche « connect() to unix:/run/php/php8.x-fpm.sock failed (2: No such file or directory) ».
• Une réponse aux en-têtes trop gros : trop de cookies ou d’en-têtes dépassent le tampon de nginx. Le message est « upstream sent too big header while reading response header from upstream ».
• Une tâche trop lourde : import de produits, sauvegarde, régénération de miniatures ou tâche planifiée (cron) qui épuise la mémoire. Le fichier debug.log contient alors « Allowed memory size of … bytes exhausted ».
• Un souci réseau, plus rare : pare-feu, IP d’origine modifiée chez Cloudflare, serveur qui redémarre.

Comment réparer une erreur 502 sur WordPress, étape par étape ?

Avant toute manipulation, sauvegardez les fichiers et la base de données depuis votre espace d’hébergement. Rechargez ensuite le site après chaque étape : dès que l’erreur disparaît, vous tenez la cause.

1. Recharger, tester ailleurs et vérifier l’état de l’hébergeur

Un 502 de quelques secondes peut venir d’un redémarrage du serveur. Rechargez avec Ctrl + F5, testez depuis un téléphone en 4G et consultez les incidents en cours chez votre hébergeur. Au-delà de cinq minutes, passez à la suite.

2. Contourner Cloudflare pour tester le serveur d’origine

Si votre domaine passe par Cloudflare, interrogez directement votre serveur en indiquant son adresse IP (visible dans votre espace d’hébergement). La commande suivante, à lancer dans un terminal, affiche le code renvoyé par le serveur lui-même ; remplacez le domaine et l’IP par les vôtres.

curl -sI --resolve www.example.fr:443:203.0.113.10 https://www.example.fr/ | head -n 1

Si la réponse est « HTTP/2 502 » ou « HTTP/1.1 502 », le problème est bien sur votre serveur et les étapes suivantes s’appliquent. Si elle est « 200 », le serveur fonctionne : vérifiez dans Cloudflare l’adresse IP de l’enregistrement DNS et le mode SSL.

3. Lire le journal d’erreurs du serveur

C’est l’étape qui fait gagner le plus de temps. Sur un hébergement mutualisé, le journal est dans l’espace client (rubrique « Logs » ou « Journaux d’erreurs »). Sur un VPS sous Debian ou Ubuntu, ces commandes affichent les dernières erreurs (adaptez la version de PHP).

sudo tail -n 50 /var/log/nginx/error.log
sudo grep -E "max_children|SIGSEGV|SIGBUS" /var/log/php8.3-fpm.log | tail -n 20
systemctl status php8.3-fpm

Rapprochez le message trouvé de la liste des causes ci-dessus : « pm.max_children » renvoie à l’étape 8, « too big header » à l’étape 9, « No such file or directory » sur le fichier .sock à un PHP-FPM arrêté, « SIGSEGV » ou « upstream prematurely closed connection » à une extension ou un module PHP qui plante (étapes 4 à 7). Si PHP-FPM est arrêté, un sudo systemctl restart php8.3-fpm remet souvent le site en ligne; cherchez ensuite pourquoi il s’était arrêté.

4. Activer le journal de débogage de WordPress

Le mode débogage enregistre les erreurs PHP de WordPress dans un fichier sans les montrer aux visiteurs. Ouvrez le fichier wp-config.php par FTP ou par le gestionnaire de fichiers de l’hébergeur, et placez ces lignes juste avant la ligne « C’est tout, ne touchez pas à ce qui suit ! » (ou « That’s all, stop editing! »).

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

Rechargez la page en erreur puis ouvrez wp-content/debug.log : la dernière « PHP Fatal error » indique le fichier fautif, et son chemin (wp-content/plugins/nom-de-l-extension/…) désigne directement l’extension en cause. Notre article sur l’erreur critique WordPress détaille la lecture de ce fichier. Pensez à remettre WP_DEBUG à false une fois la panne réglée.

5. Désactiver toutes les extensions, puis les réactiver une à une

Par FTP, renommez le dossier wp-content/plugins en plugins-off pour désactiver toutes les extensions. Si le site revient, rendez-lui son nom, puis renommez un à un les sous-dossiers jusqu’à trouver l’extension fautive. Avec un accès SSH, WP-CLI (l’outil en ligne de commande officiel de WordPress) fait la même chose plus proprement.

wp plugin list --status=active
wp plugin deactivate --all --skip-plugins --skip-themes
wp plugin activate nom-de-l-extension

L’option –skip-plugins évite que la commande plante à son tour.

6. Tester avec un thème par défaut

Si les extensions ne sont pas en cause, activez un thème par défaut comme Twenty Twenty-Five en renommant le dossier de votre thème dans wp-content/themes ou avec wp theme activate twentytwentyfive. Si le 502 disparaît, le thème ou son fichier functions.php est en cause.

7. Vérifier la version de PHP et ses limites

Le menu Outils, puis Santé du site, onglet Infos, rubrique Serveur, affiche la version de PHP et ses limites. Un passage récent à une version plus récente peut faire planter une vieille extension : revenir temporairement à la précédente dans l’espace d’hébergement permet de le confirmer. Si debug.log signale une mémoire épuisée, augmentez la limite comme expliqué dans notre fiche sur la mémoire PHP.

8. Augmenter le nombre de processus PHP-FPM (VPS et serveurs dédiés)

Si le journal affiche « WARNING: [pool www] server reached pm.max_children setting (5), consider raising it », le nombre maximal de processus PHP est trop bas pour votre trafic. Mesurez d’abord la mémoire moyenne d’un processus, puis calculez la valeur possible : environ 70 % de la mémoire vive, moins ce qu’utilisent le système et la base de données, divisé par la mémoire d’un processus.

ps -eo rss,cmd | grep '[p]hp-fpm: pool' | awk '{s+=$1; n++} END {print s/n/1024 " Mo en moyenne, " n " processus"}'
sudo nano /etc/php/8.3/fpm/pool.d/www.conf
# exemple pour 4 Go de RAM et des processus de 60 Mo environ :
pm.max_children = 30
sudo systemctl reload php8.3-fpm

N’augmentez jamais cette valeur à l’aveugle : trop de processus fait tomber tout le serveur. En mutualisé, seul l’hébergeur peut le modifier.

9. Agrandir les tampons de nginx si les en-têtes sont trop gros

Pour le message « upstream sent too big header », ajoutez ces directives dans le bloc qui traite les fichiers PHP de la configuration nginx du site, testez la configuration, puis rechargez nginx.

location ~ \.php$ {
    # ... directives existantes ...
    fastcgi_buffer_size 32k;
    fastcgi_buffers 16 16k;
}

sudo nginx -t
sudo systemctl reload nginx

Si nginx relaie vers Apache au lieu de PHP-FPM, ce sont les directives proxy_buffer_size et proxy_buffers qui jouent ce rôle.

Comment éviter que l’erreur 502 revienne ?

Un 502 qui revient signale un serveur trop juste ou une extension fragile, et quelques réglages limitent fortement le risque.

• Faites les mises à jour une par une, après une sauvegarde, pour repérer tout de suite celle qui pose problème.
• Activez un cache de pages : une page servie depuis le cache ne sollicite pas PHP.
• Remplacez le cron de WordPress, lancé à chaque visite, par une vraie tâche planifiée du serveur : ajoutez define( 'DISABLE_WP_CRON', true ); dans wp-config.php et programmez wp cron event run --due-now toutes les cinq minutes.
• Limitez les robots agressifs avec un pare-feu, surtout sur la recherche et les filtres.
• Choisissez une offre d’hébergement à la mesure de votre trafic : nos critères sont dans notre article sur le choix d’un hébergement WordPress. Si c’est surtout l’administration qui rame avant de tomber en 502, lisez aussi notre guide sur l’administration lente.

Quand faut-il faire appel à un professionnel ?

Il vaut mieux passer la main dès que l’erreur persiste après la désactivation des extensions et le changement de thème, ou dès que la solution passe par la configuration du serveur (PHP-FPM, nginx) sans que vous soyez à l’aise en ligne de commande. C’est aussi le cas pour une boutique qui perd des commandes, ou si les journaux citent des fichiers PHP inconnus, signe possible d’un piratage. Vous pouvez d’abord parcourir nos autres guides dans la rubrique Résoudre une panne.