502 Bad Gateway : ce que ça signifie vraiment et comment le corriger
Vous ouvrez votre site et, au lieu du contenu, vous voyez une page blanche affichant 502 Bad Gateway. Ça fait peur, mais dans la plupart des cas la solution est simple. Voyons ce qui se passe et comment remettre votre site en ligne.
Que signifie réellement le 502 ?
Lorsqu'un visiteur demande une page, la requête passe par deux couches : un serveur web frontend (généralement Nginx) et un serveur d'application backend (PHP-FPM, Apache, Node.js ou autre). Nginx reçoit la requête, la transmet au backend et attend une réponse.
Un 502 Bad Gateway signifie que Nginx a essayé d'obtenir une réponse du backend, mais a reçu quelque chose d'invalide ou n'a reçu aucune réponse. Le backend s'est planté, a refusé la connexion ou a renvoyé quelque chose qu'Nginx n'a pas pu interpréter.
Une idée reçue répandue : 502 ne signifie pas que votre serveur est hors ligne. Le serveur lui-même fonctionne parfaitement — c'est l'application derrière Nginx qui pose problème.
Les causes les plus fréquentes
Le service backend s'est arrêté. C'est la raison la plus courante. PHP-FPM a planté, Apache est bloqué ou un processus Node.js est mort silencieusement. Nginx n'a tout simplement rien à qui parler.
Le serveur manque de mémoire RAM. Lorsque la mémoire vient à manquer, Linux peut tuer automatiquement les processus les plus gourmands en ressources. Ce mécanisme s'appelle l'OOM killer, et PHP-FPM ou MySQL en sont généralement les premières victimes. Si cela arrive régulièrement, pensez à ajouter un fichier swap comme filet de sécurité.
Le pool de workers PHP-FPM est épuisé. Si votre site reçoit plus de requêtes simultanées que PHP-FPM ne peut en gérer, les nouvelles requêtes s'accumulent dans la file d'attente et finissent par expirer. Cela arrive souvent quand les robots des moteurs de recherche crawlent votre site de manière trop agressive — nous avons écrit à ce sujet dans notre guide de blocage des bots.
Socket ou port mal configuré. Nginx s'attend à trouver PHP-FPM sur un socket Unix ou un port TCP précis. Si le chemin dans la configuration Nginx ne correspond pas à la configuration PHP-FPM, vous verrez des erreurs 502 immédiatement après tout changement.
Comment diagnostiquer le problème
Pour effectuer les étapes suivantes, connectez-vous à votre serveur via SSH. Vous pouvez apprendre comment faire dans notre article sur SSH.
Étape 1. Vérifiez si le backend tourne
Vérifiez le statut de votre service backend :
sudo systemctl status php8.2-fpm
Remplacez php8.2-fpm par votre version PHP réelle ou le nom de votre service backend. Si la sortie indique inactive (dead) ou failed, voilà votre problème. Redémarrez-le :
sudo systemctl restart php8.2-fpm
Vérifiez ensuite le statut à nouveau pour vous assurer qu'il a démarré correctement.
Étape 2. Consultez le log d'erreurs Nginx
Le log d'erreurs vous dit presque toujours exactement ce qui s'est passé:
sudo tail -30 /var/log/nginx/error.log
Si vous utilisez FASTPANEL®, vous pouvez aussi consulter les logs directement dans l'interface web : ouvrez la fiche du site, allez dans la section « Logs » et consultez l'onglet « Frontend Error Log ».
Voici les messages d'erreur les plus courants et leur signification :
connect() failed - Connection refused — le service backend ne fonctionne pas. Redémarrez-le comme indiqué à l'Étape 1.
connect() failed - No such file or directory — Nginx essaie d'atteindre un socket Unix qui n'existe pas. Vérifiez que le chemin du socket dans votre configuration Nginx correspond bien à celui que PHP-FPM crée réellement.
upstream sent too big header — le backend a renvoyé des en-têtes HTTP trop volumineux pour le buffer par défaut. Ajoutez ces lignes dans la configuration de votre site Nginx, à l'intérieur du bloc server :
fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;
Après modification, testez la configuration et rechargez Nginx :
sudo nginx -t && sudo systemctl reload nginx
Étape 3. Vérifiez les ressources du serveur
free -h
Si la colonne available affiche moins de 100–200 Mo de mémoire libre, votre serveur manque probablement de RAM. Vérifiez ce qui la consomme :
ps aux --sort=-%mem | head -10
Si le manque de mémoire est la cause principale, la solution temporaire la plus rapide est d'ajouter un fichier swap. Cependant, le swap sur disque est bien plus lent que la RAM et ne doit pas être considéré comme une solution permanente. Si votre serveur manque régulièrement de mémoire, il est temps d'optimiser vos applications ou de passer à un plan avec plus de RAM.
Conclusion
Un 502 Bad Gateway est presque toujours un problème de backend — un service planté, des workers épuisés ou pas assez de mémoire. Vérifiez le statut du backend, lisez le log d'erreurs Nginx et examinez votre consommation de ressources. Dans la grande majorité des cas, vous trouverez la réponse en quelques minutes.
Si vous préférez ne pas gérer ça seul, chez kodu.cloud nous proposons un support technique gratuit 24h/24 et 7j/7 avec chaque VPS et serveur dédié. Tous nos clients reçoivent également FASTPANEL®* Extended sans frais supplémentaires, ce qui simplifie considérablement l'analyse des logs et la gestion des services via une interface web.