Erreur 502 Bad Gateway : Diagnostic Complet

L'erreur 502 Bad Gateway est l'une des plus frustrantes à diagnostiquer. Elle indique que le serveur proxy (Nginx, Apache, ou un load balancer) n'a pas pu obtenir une réponse valide du serveur backend. Le problème n'est pas sur le proxy lui-même, mais quelque part en amont.

Cette erreur peut avoir des dizaines de causes différentes : crash du service PHP-FPM, surcharge de la base de données, timeout de l'application, ou simple mauvaise configuration. La clé du diagnostic est de savoir exactement où chercher.

Ce guide vous accompagne étape par étape dans le diagnostic d'une erreur 502. Des vérifications basiques aux commandes avancées, vous aurez toutes les clés pour identifier et résoudre le problème rapidement.

Comprendre l'Erreur 502 Bad Gateway

L'erreur 502 se produit dans une architecture avec un proxy inverse :

• Le rôle du proxy : Nginx ou Apache agit comme intermédiaire entre l'utilisateur et votre application. Il reçoit les requêtes et les transmet au backend (PHP-FPM, Node.js, Gunicorn...).
• Communication échouée : Le proxy a essayé de contacter le backend mais n'a pas obtenu de réponse valide. Le backend peut être down, saturé, ou avoir retourné une réponse malformée.
• Différence avec 503 : Une 503 dit "je suis surchargé, réessayez plus tard". Une 502 dit "je n'arrive pas à communiquer avec le backend". La 502 est généralement plus grave.
• Impact utilisateur : L'utilisateur voit une page d'erreur et ne peut pas accéder au service. Contrairement à une lenteur, il n'y a aucune possibilité d'attendre - l'action a définitivement échoué.

Causes Principales de l'Erreur 502

Voici les causes les plus fréquentes d'une erreur 502 Bad Gateway :

• Service backend arrêté : PHP-FPM, Node.js, ou Gunicorn s'est arrêté ou a crashé. Le proxy n'a personne à qui parler. Cause la plus fréquente.
• Timeout dépassé : L'application met trop de temps à répondre et le proxy abandonne. Requête trop lente, base de données saturée, ou appel à un service externe bloqué.
• Ressources épuisées : Le backend manque de workers/threads pour traiter les requêtes. Toutes les connexions sont occupées et les nouvelles sont refusées.
• Socket/port inaccessible : Le proxy essaie de se connecter au mauvais socket ou port, ou les permissions sont incorrectes. Problème de configuration.
• Mémoire insuffisante : Le processus backend a été tué par l'OOM killer du système. Le serveur manque de RAM et a sacrifié le service.

Étapes de Diagnostic

Suivez ces étapes pour identifier la cause de l'erreur 502 :

1. Vérifier l'état du backend : Commencez par vérifier si PHP-FPM, Node, ou votre service backend est en cours d'exécution. C'est la cause numéro 1.
2. Consulter les logs du proxy : Les logs Nginx/Apache contiennent le message d'erreur exact : "upstream timed out", "connection refused", etc.
3. Vérifier les logs backend : PHP-FPM, Node.js, ou votre framework logguent généralement la raison du crash ou de l'échec.
4. Contrôler les ressources : Vérifiez CPU, RAM, et disque. Un système saturé peut provoquer des comportements erratiques.
5. Tester la connexion directe : Essayez de contacter le backend directement (curl vers le port/socket) pour isoler le problème.

Commandes de Diagnostic

Voici les commandes essentielles pour diagnostiquer une erreur 502 :

# Vérifier l'état de PHP-FPM
systemctl status php-fpm
journalctl -u php-fpm -n 50

# Vérifier l'état de Nginx
systemctl status nginx
tail -100 /var/log/nginx/error.log

# Rechercher les erreurs 502 récentes
grep "502" /var/log/nginx/access.log | tail -20

# Vérifier les ressources système
free -h
df -h
top -bn1 | head -20

# Tester la connexion au socket PHP-FPM
curl --unix-socket /var/run/php/php-fpm.sock http://localhost/status

# Vérifier les connexions réseau
ss -tlnp | grep -E "php|nginx"

Ces commandes vous donnent une vue complète : état des services, logs d'erreur, ressources système, et connectivité. Commencez par systemctl status pour une première évaluation rapide.

Solutions Selon la Cause

Une fois la cause identifiée, appliquez la solution appropriée :

• Backend arrêté : Redémarrez le service (systemctl restart php-fpm). Vérifiez les logs pour comprendre pourquoi il s'est arrêté et corrigez la cause racine.
• Timeout dépassé : Augmentez les timeouts dans Nginx (proxy_read_timeout, proxy_connect_timeout) et optimisez les requêtes lentes côté application.
• Workers insuffisants : Augmentez le nombre de workers PHP-FPM (pm.max_children) ou Node.js. Surveillez la RAM disponible.
• Mémoire épuisée : Ajoutez de la RAM ou optimisez la consommation mémoire. Configurez des limits appropriés pour éviter l'OOM killer.

Prévention des Erreurs 502

Mieux vaut prévenir que guérir. Voici comment éviter les futures erreurs 502 :

• Monitoring proactif : Surveillez les temps de réponse et la disponibilité avec MoniTao. Une dégradation progressive précède souvent une 502.
• Alertes sur les métriques : Configurez des alertes sur CPU > 80%, RAM > 90%, et nombre de connexions. Agissez avant la saturation.
• Health checks : Configurez des health checks sur votre load balancer pour détecter les backends défaillants et les exclure automatiquement.
• Redondance : Utilisez plusieurs instances backend derrière un load balancer. Si une instance crashe, les autres prennent le relais.

Questions Fréquentes

Conclusion

L'erreur 502 Bad Gateway est un symptôme qui pointe vers un problème de communication entre votre proxy et votre backend. La cause racine peut être un crash, un timeout, ou un épuisement de ressources.

Avec MoniTao, vous détectez ces problèmes avant qu'ils n'impactent vos utilisateurs. Les alertes de timeout et de temps de réponse vous préviennent des dégradations qui précèdent souvent une 502 complète.

Prêt à dormir sur vos deux oreilles ?

Commencez gratuitement, sans carte bancaire.

Créer mon compte Voir les tarifs