Erreur 502 Bad Gateway sur WordPress : PHP-FPM, nginx, proxy

502 Bad Gateway

En anglais : 502 Bad Gateway

Vous demandez une page et le navigateur affiche « 502 Bad Gateway » sur fond blanc (parfois « Bad gateway » dans la page d’un CDN, ou « Proxy Error » sous Apache). Le message est sec, sans lien avec WordPress. Il peut toucher toutes les pages, seulement l’administration, ou apparaître par intermittence aux heures de pointe.

Ce code ne signale pas un défaut dans vos contenus. Il indique que deux serveurs ne se parlent plus correctement, et qu’il faut regarder du côté du serveur web, de PHP-FPM, ou d’un proxy placé devant.

Ce que signifie cette erreur

« 502 Bad Gateway » est un code HTTP de la famille des erreurs serveur. Il est renvoyé par un serveur qui agit comme passerelle ou comme proxy et qui reçoit une réponse invalide, ou aucune réponse, d’un serveur en amont. Avec WordPress, la chaîne est presque toujours : navigateur, éventuellement un CDN (comme Cloudflare), nginx ou Apache, puis PHP-FPM, qui exécute WordPress. nginx et PHP-FPM dialoguent en FastCGI, via un socket Unix (/run/php/php8.2-fpm.sock, par exemple) ou un port TCP local.

Le 502 survient quand cette conversation s’arrête : le service PHP-FPM est arrêté, le socket est introuvable ou inaccessible, un processus PHP s’est terminé brutalement (plantage, mémoire épuisée, arrêt par le système) avant d’avoir répondu, ou la réponse est mal formée. Le cœur de WordPress n’a aucun rôle direct, mais WordPress peut en être l’origine : une extension qui fait planter PHP, une page trop gourmande, ou des en-têtes de réponse démesurés.

Ne le confondez pas avec ses voisins. Un délai dépassé se traduit le plus souvent par une erreur 504 ; une surcharge ou une maintenance du serveur par un 503 ; une erreur PHP interne par une erreur 500. Mais, selon la configuration, certains dépassements (processus FPM terminé après request_terminate_timeout) apparaissent aussi en 502.

Diagnostic rapide

Symptôme / constat	Cause probable	À vérifier
502 sur tout le site, immédiatement	PHP-FPM arrêté, ou socket introuvable	systemctl status php8.2-fpm, chemin du socket
502 intermittents, surtout aux heures de pointe	Pool saturé (pm.max_children atteint)	Journal FPM : « server reached pm.max_children »
502 sur une page ou une action précise (import, export, admin-ajax)	Processus PHP tué ou terminé en cours de requête	Journal FPM : « exited on signal », journal système
Journal nginx : « upstream sent too big header »	En-têtes de réponse trop volumineux (cookies, redirections)	Valeur de fastcgi_buffer_size
Journal nginx : « (13: Permission denied) » sur le socket	Droits du socket ne correspondant pas à l’utilisateur nginx	listen.owner, listen.group, listen.mode
Le 502 s’affiche avec un logo de CDN	Le CDN n’obtient pas de réponse de votre serveur d’origine	Accès direct à l’origine, pare-feu

Les causes les plus fréquentes

1. Le service PHP-FPM est arrêté ou planté (mise à jour du système, redémarrage, crash), ou le socket a changé de chemin.
2. Le pool PHP-FPM est saturé : tous les processus sont occupés et les requêtes en attente finissent en erreur.
3. Un processus PHP est tué par le noyau (manque de mémoire) ou plante (erreur de segmentation) à cause d’une extension ou d’un module PHP défectueux.
4. Une requête trop longue est interrompue par request_terminate_timeout avant la fin de son traitement.
5. Un défaut de configuration : fastcgi_pass ne correspond pas au listen du pool, droits du socket, en-têtes trop gros.
6. Un CDN ou un proxy qui n’arrive pas à joindre votre serveur d’origine.

Solutions pas à pas

Si vous modifiez des fichiers de configuration, gardez toujours une copie de l’original. Du moins invasif au plus technique :

1. Déterminer l’étendue et réessayer

Rechargez la page après une minute, testez une autre page, puis l’administration. Un 502 passager indique plutôt une saturation ou un redémarrage ; un 502 permanent évoque un service arrêté. Si un CDN est actif, essayez de joindre directement le serveur d’origine :

curl -sI --resolve www.exemple.fr:443:IP_DU_SERVEUR https://www.exemple.fr/

Si la réponse directe est correcte, le problème se situe entre le CDN et votre serveur (pare-feu, filtrage d’adresses, délais). Sur un hébergement mutualisé, vous ne pouvez pas aller plus loin : signalez l’incident au support en précisant l’heure.

2. Lire les journaux du serveur

Chaque 502 laisse une trace côté serveur, avec la cause exacte :

sudo tail -n 50 /var/log/nginx/error.log
sudo tail -n 50 /var/log/php8.2-fpm.log
sudo systemctl status php8.2-fpm

Les chemins et la version de PHP dépendent de votre installation ; sur un mutualisé, les journaux sont dans le panneau d’hébergement. Les lignes types sont :

• connect() to unix:/run/php/php8.2-fpm.sock failed (2: No such file or directory) : PHP-FPM est arrêté ou le socket a un autre nom ;
• connect() … failed (111: Connection refused) : rien n’écoute sur le port TCP indiqué ;
• connect() … failed (13: Permission denied) : droits du socket ;
• upstream prematurely closed connection while reading response header from upstream ou recv() failed (104: Connection reset by peer) : le processus PHP s’est arrêté en cours de route ;
• upstream sent too big header while reading response header from upstream : en-têtes trop volumineux.

Notre article sur le diagnostic d’un 502 entre nginx et PHP-FPM détaille cette lecture croisée.

3. Redémarrer PHP-FPM et contrôler la configuration

Si le service est arrêté, relancez-le, après avoir validé la configuration :

sudo php-fpm8.2 -t
sudo nginx -t
sudo systemctl restart php8.2-fpm
sudo systemctl reload nginx

Assurez-vous que le chemin indiqué par fastcgi_pass dans nginx est identique à la directive listen du pool PHP-FPM utilisé par le site (dans /etc/php/8.2/fpm/pool.d/). Côté droits, le propriétaire du socket doit pouvoir être lu par nginx :

; pool PHP-FPM
listen = /run/php/php8.2-fpm-monsite.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660

4. Redimensionner le pool PHP-FPM

Si le journal contient « server reached pm.max_children setting », augmentez le nombre de processus dans la limite de la mémoire disponible : divisez la RAM allouée à PHP par la consommation moyenne d’un processus (mesurable avec ps). Exemple de pool :

pm = dynamic
pm.max_children = 40
pm.start_servers = 10
pm.min_spare_servers = 5
pm.max_spare_servers = 15
pm.max_requests = 500
pm.status_path = /fpm-status

Rechargez ensuite PHP-FPM. Ne vous contentez pas d’augmenter la valeur à l’aveugle : un pool trop grand épuise la RAM et déclenche l’arrêt de processus par le système. Voir le tuning avancé des pools PHP-FPM et l’article sur l’OOM killer.

5. Chercher le processus qui plante

Si le journal FPM indique « exited on signal 9 » ou « signal 11 », un processus est tué ou plante. Contrôlez le journal du noyau et la mémoire :

sudo dmesg | grep -i -E 'out of memory|killed process'
free -h

Pour savoir si une extension WordPress est en cause, écartez-les sans toucher à la base en renommant le dossier, par SFTP ou en SSH, puis testez :

mv wp-content/plugins wp-content/plugins.off
mkdir wp-content/plugins

Si le site répond, remettez les extensions une à une (rétablissez le dossier, puis renommez chaque sous-dossier). Consultez aussi la fiche sur la mémoire épuisée : une page qui dépasse memory_limit provoque une erreur PHP, tandis qu’un manque de RAM sur le serveur tue le processus et donne ce 502.

6. Ajuster les délais et les tampons

Si les requêtes lentes sont coupées, alignez request_terminate_timeout (pool PHP-FPM) et fastcgi_read_timeout (nginx), sans les relever au-delà du nécessaire. Pour l’erreur « too big header », augmentez les tampons dans le bloc location ~ \.php$ :

fastcgi_buffer_size 32k;
fastcgi_buffers 16 16k;
fastcgi_read_timeout 120s;

Avec Apache et mod_proxy_fcgi, le délai se règle par ProxyTimeout dans le vhost ; vérifiez aussi le journal d’erreurs d’Apache (/var/log/apache2/error.log sous Debian ou Ubuntu). Le cas d’un processus PHP qui n’en finit plus est traité dans la fiche sur le temps d’exécution dépassé.

Sans accès à l’administration

Le 502 ne dépend pas de l’administration de WordPress : tout se règle en SSH (journaux, services, configuration) ou, sur un mutualisé, par le support. Pour désactiver une extension sans administration, renommez son dossier par SFTP.

Prévenir l’erreur

• Dimensionnez le pool PHP-FPM d’après la mémoire réelle, et activez pm.status_path pour surveiller la saturation.
• Mettez en place un cache de page pour que les visiteurs n’exécutent pas PHP à chaque requête.
• Surveillez la RAM, les redémarrages et les journaux, avec des alertes.
• Testez les mises à jour de PHP et des extensions sur un double avant la production.
• Testez la résilience de votre architecture en simulant la perte d’un processus : par exemple en tuant volontairement un worker PHP-FPM sur un environnement de test.

Questions fréquentes