Erreur 502 Bad Gateway : trouver la cause et la corriger

Ce que signifie l'erreur

Un 502 est la réponse d'un serveur qui fonctionne. Le serveur web en façade (nginx, Apache, un répartiteur de charge ou un CDN comme Cloudflare) a reçu la requête, l'a transmise à l'application derrière lui (PHP-FPM, un processus Node.js ou Python) et n'a rien reçu d'utilisable en retour : connexion refusée, coupée, ou réponse illisible. « Gateway », c'est le serveur en façade ; « bad », c'est ce qui est revenu de l'arrière. Un 502 dit donc deux choses : devant, ça tourne ; derrière, quelque chose est arrêté ou cassé.

Causes fréquentes

1. Le processus de l'application ne tourne pas. PHP-FPM a planté ou a été arrêté, le processus Node.js est mort, le conteneur s'est terminé.
2. L'application est saturée. Tous les workers PHP-FPM sont occupés, la file est pleine, les nouvelles connexions sont refusées. Souvent après un pic de visites ou une requête SQL lente.
3. Mauvais socket ou mauvais port. Après un changement de version de PHP, nginx pointe encore vers php8.2-fpm.sock alors que le nouveau pool écoute sur php8.4-fpm.sock.
4. Délais trop courts. Le backend répond, mais trop tard pour le serveur web. Certaines configurations le signalent en 502, d'autres en 504 Gateway Timeout.
5. Le backend envoie des en-têtes trop gros. Typique des frameworks qui chargent les cookies.
6. Le CDN n'atteint pas votre serveur. Une page 502 au logo Cloudflare signifie que Cloudflare n'a rien reçu de votre serveur : pare-feu, mauvaise IP après un déménagement, ou serveur éteint.

Si vous êtes visiteur

Un 502 sur un site qui n'est pas le vôtre ne se corrige pas de votre côté. Rechargez après une minute ; s'il persiste, seul l'exploitant peut agir.

Si c'est votre site : vérifier d'abord

Est-il down pour tout le monde ? Lancez le Site down checker : code HTTP vu de l'extérieur, et qui a répondu, CDN ou serveur.

Hébergement mutualisé ou constructeur de site ? Un 502 y est presque toujours un problème de l'hébergeur (un pool PHP saturé sur un serveur partagé). Passez au message prêt à envoyer, plus bas.

Votre propre serveur : connectez-vous en SSH et lisez ce que dit le serveur web.

# nginx : les dernières erreurs, les plus récentes en bas
sudo tail -n 50 /var/log/nginx/error.log

# Apache (Debian/Ubuntu)
sudo tail -n 50 /var/log/apache2/error.log

Lignes typiques et leur sens :

• connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory) : PHP-FPM ne tourne pas, ou le chemin du socket est faux.
• connect() failed (111: Connection refused) while connecting to upstream : rien n'écoute sur le port du backend.
• upstream prematurely closed connection : le backend a planté en répondant, souvent une erreur fatale PHP ou un manque de mémoire.
• upstream sent too big header : relevez fastcgi_buffer_size dans nginx.
• (11: Resource temporarily unavailable) : tous les workers PHP-FPM sont occupés.

Solutions sur votre propre serveur

1. Démarrer le service arrêté

systemctl status php8.3-fpm
sudo systemctl start php8.3-fpm

# applications Node.js ou Python sous systemd
sudo systemctl restart mon-app

S'il ne démarre pas, la raison est dans journalctl -u php8.3-fpm -n 50. Le plus fréquent : un disque plein (df -h), puis une erreur de syntaxe dans un pool (sudo php-fpm8.3 -t).

2. Corriger le socket ou le port

Comparez l'adresse à laquelle nginx se connecte et celle sur laquelle PHP-FPM écoute :

grep -r fastcgi_pass /etc/nginx/sites-enabled/
grep -r '^listen' /etc/php/*/fpm/pool.d/

Les deux doivent coïncider. Après toute modification, testez avant de recharger :

sudo nginx -t && sudo systemctl reload nginx

Avec Apache et mod_proxy_fcgi, même règle pour la ligne SetHandler "proxy:unix:/run/php/php8.3-fpm.sock|fcgi://localhost" ; test avec sudo apachectl configtest.

3. Donner de l'air à PHP-FPM

Si le journal signale server reached pm.max_children, relevez la limite dans le fichier du pool (/etc/php/8.3/fpm/pool.d/www.conf) :

pm = dynamic
pm.max_children = 20
pm.start_servers = 4
pm.min_spare_servers = 2
pm.max_spare_servers = 6

Chaque worker consomme de la mémoire ; vérifiez free -m avant d'augmenter, et cherchez la requête lente ou l'extension qui bloque les workers.

4. Le cas WordPress

Un 502 juste après la mise à jour d'une extension ou d'un thème : PHP tombe à chaque requête sur une erreur fatale ou un manque de mémoire. Renommez le dossier de l'extension par SFTP ou SSH (wp-content/plugins/nom-extension en nom-extension.off) ou lancez wp plugin deactivate nom-extension, puis rechargez. Relevez memory_limit si journalctl montre « Allowed memory size exhausted ».

5. Derrière Cloudflare

Vérifiez si le serveur d'origine répond en direct : curl -I https://IP-DU-SERVEUR -H 'Host: example.com' -k. Si oui, le pare-feu bloque peut-être les plages d'adresses de Cloudflare, ou l'enregistrement DNS chez Cloudflare pointe vers une ancienne IP.

Si le problème est chez votre hébergeur

Sur un hébergement mutualisé, vous ne pouvez pas redémarrer PHP-FPM. Envoyez ceci à votre hébergeur :

Bonjour, mon site example.com renvoie « 502 Bad Gateway » depuis environ 14 h 30 (UTC). Une vérification depuis l'extérieur le confirme ; je n'ai rien modifié de mon côté. Pourriez-vous vérifier les processus PHP et le serveur web de mon compte et m'indiquer quand le site sera de retour ?

Pour que cela ne se reproduise pas

Un 502, c'est presque toujours un backend arrêté ou saturé, et les deux se voient avant que les visiteurs ne le remarquent : un service PHP-FPM arrêté, une mémoire qui se raréfie, un disque qui se remplit. Le monitoring serveur avec l'agent serveur signale exactement cela depuis l'intérieur ; les vérifications depuis l'extérieur attrapent le 502 dès qu'il apparaît. Sur votre propre serveur ou un hébergement mutualisé avec accès SSH, l'intervention rapide redémarre le service arrêté si son test de configuration réussit ; si la cause est plus profonde, l'intervention approfondie prend le relais, 24 h/24.