Diagnostiquer une erreur 502/504 Bad Gateway sur un serveur web¶

Contexte¶

Lorsque vous hébergez des applications web, vous utilisez souvent un serveur "frontal" (reverse proxy) comme Nginx ou HAProxy qui redirige le trafic vers une application en arrière-plan (Node.js, PHP-FPM, Gunicorn, Tomcat, etc.).

Si le lien entre le frontal et l'application casse, vous obtenez généralement l'une de ces deux erreurs : - 502 Bad Gateway : Le proxy a pu contacter l'application, mais il a reçu une réponse invalide ou inattendue, ou bien la connexion a été refusée (service éteint). - 504 Gateway Timeout : Le proxy a contacté l'application, mais n'a pas reçu de réponse dans le temps imparti (l'application est bloquée ou surchargée).

Problème¶

L'utilisateur se connecte au site web et voit s'afficher une page d'erreur blanche de son navigateur ou une page générée par Nginx mentionnant "502 Bad Gateway" ou "504 Gateway Timeout".

502 Bad Gateway
nginx/1.18.0 (Ubuntu)

Procédure de Diagnostic¶

Étape 1 : Vérifier le statut du service backend¶

Dans 90% des cas d'une erreur 502, le service backend (PHP-FPM, Node, Python, etc.) est tout simplement arrêté, a crashé, ou est en redémarrage en boucle.

Vérifiez le statut du service sous-jacent. Par exemple pour php8.1-fpm :

sudo systemctl status php8.1-fpm

Si le service est en erreur, relancez-le :

sudo systemctl restart php8.1-fpm

Étape 2 : Analyser les journaux du proxy (Nginx/Apache)¶

Si le service semble actif, le serveur proxy détient la réponse exacte dans ses logs d'erreur. Pour Nginx, les logs sont généralement dans /var/log/nginx/error.log.

sudo tail -n 20 /var/log/nginx/error.log

connect() failed (111: Connection refused) while connecting to upstream

Étape 3 : Vérifier les ports en écoute¶

Le proxy est configuré pour joindre le backend sur une certaine adresse (ex: 127.0.0.1:8080 ou un socket UNIX /var/run/php.sock).

Vérifiez si l'application écoute bien là où le proxy la cherche :

sudo ss -tulpn | grep 8080

Étape 4 : Diagnostiquer les lenteurs (Erreur 504)¶

Si le problème est une 504 Gateway Timeout, le backend est vivant mais trop lent. Cela peut être causé par : - Une base de données surchargée (requête très longue). - Un appel à une API externe distante qui ne répond pas. - Une boucle infinie dans le code de l'application.

Regardez cette fois-ci les logs de votre application ou de la base de données. Vous pouvez également augmenter temporairement le timeout côté Nginx dans votre configuration si c'est un traitement normal long :

# Dans le bloc location
proxy_read_timeout 300;
proxy_connect_timeout 300;
proxy_send_timeout 300;

N'oubliez pas de recharger Nginx après modification :

sudo systemctl reload nginx

Aide-mémoire¶

Vérification¶

Pour vérifier qu'une erreur 502/504 est résolue : 1. Lancez une requête vers votre serveur en utilisant curl :

curl -I https://votresite.com

HTTP/2 200 
server: nginx
content-type: text/html; charset=UTF-8

Ressources¶

• Documentation Nginx - Proxy — Guide officiel sur le reverse proxy Nginx.
• MDN Web Docs - 502 Bad Gateway — Explication de la spécification HTTP.
• MDN Web Docs - 504 Gateway Timeout — Explication de la spécification HTTP.