502 Mauvaise passerelle : ce que cela signifie réellement et comment y remédier
Vous ouvrez votre site web et, au lieu du contenu, vous voyez une page blanche indiquant 502 Mauvaise passerelle. Cela peut sembler effrayant, mais dans la plupart des cas, la solution est simple. Analysons ce qui se passe et comment rétablir votre site.
Que signifie réellement le 502 ?
Lorsqu'un visiteur demande une page, la requête passe généralement par deux couches : un serveur web frontend (généralement Nginx) et un serveur d'applications backend (PHP-FPM, Apache, Node.js ou autre). Nginx reçoit la requête, la transmet au backend et attend une réponse.
Une erreur 502 Mauvaise passerelle 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 a soit planté, soit refusé la connexion, soit renvoyé quelque chose que Nginx n'a pas pu interpréter.
Une idée fausse courante : 502 ne signifie pas que votre serveur est en panne. Le serveur lui-même fonctionne parfaitement ; c'est l'application derrière Nginx qui rencontre des difficultés.
Causes les plus fréquentes
Le service backend s'est arrêté. C'est la raison numéro un. PHP-FPM a planté, Apache s'est bloqué, ou un processus Node.js s'est arrêté silencieusement. Nginx n'a plus personne avec qui communiquer.
Le serveur manque de RAM. Lorsque la mémoire est faible, Linux peut tuer automatiquement les processus gourmands en ressources. Ce mécanisme s'appelle le tueur OOM (Out Of Memory killer), et PHP-FPM ou MySQL en sont généralement les premières victimes. Si cela se produit régulièrement, envisagez d'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 sont mises en file d'attente et finissent par expirer. Cela se produit souvent lorsque les robots des moteurs de recherche explorent votre site de manière trop agressive ; nous avons abordé ce sujet dans notre guide sur le blocage des robots.
Socket ou port mal configuré. Nginx s'attend à trouver PHP-FPM sur un socket Unix ou un port TCP spécifique. Si le chemin dans la configuration Nginx ne correspond pas à la configuration PHP-FPM, vous verrez des erreurs 502 immédiatement après toute modification.
Comment diagnostiquer le problème
Pour effectuer les étapes suivantes, connectez-vous à votre serveur via SSH. Vous pouvez apprendre comment faire dans notre article SSH.
Étape 1. Vérifier si le backend est en cours d'exécution
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 par le nom de votre service backend. Si la sortie indique inactive (dead) ou failed, c'est votre problème. Redémarrez-le :
sudo systemctl restart php8.2-fpm
Vérifiez ensuite à nouveau le statut pour vous assurer qu'il a démarré correctement.
Étape 2. Vérifier le journal d'erreurs Nginx
Le journal d'erreurs vous indique presque toujours exactement ce qui s'est mal passé :
sudo tail -30 /var/log/nginx/error.log
Si vous utilisez FASTPANEL®, vous pouvez également consulter les journaux directement dans l'interface web : ouvrez la carte du site, accédez à la section "Journaux" et consultez l'onglet "Journal d'erreurs Frontend".
Voici les messages d'erreur les plus courants et ce qu'ils signifient :
connect() failed - Connection refused - le service backend n'est pas en cours d'exécution. Redémarrez-le comme indiqué à l'étape 1.
connect() failed - No such file or directory - Nginx essaie d'accéder à un socket Unix qui n'existe pas. Vérifiez que le chemin du socket dans votre configuration Nginx correspond à ce 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 tampon par défaut. Ajoutez ces lignes à la configuration de votre site Nginx, à l'intérieur du bloc server :
fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;
Après la modification, testez la configuration et rechargez Nginx :
sudo nginx -t && sudo systemctl reload nginx
Étape 3. Vérifier 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 consomme la mémoire :
ps aux --sort=-%mem | head -10
Si la pression de la mémoire est la cause première, la solution temporaire la plus rapide consiste à ajouter un fichier swap. Cependant, un swap sur disque est beaucoup 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
Une erreur 502 Mauvaise passerelle est presque toujours un problème de backend : un service planté, des workers épuisés ou un manque de mémoire. Vérifiez le statut du backend, lisez le journal d'erreurs Nginx et examinez votre utilisation des ressources. Dans la grande majorité des cas, vous trouverez la réponse en quelques minutes.
Si vous préférez ne pas vous en occuper seul, chez kodu.cloud, nous offrons une assistance technique gratuite 24h/24 et 7j/7 avec chaque VPS et serveur dédié. Tous nos clients bénéficient également de FASTPANEL® Extended sans frais supplémentaires, ce qui simplifie considérablement l'analyse des journaux et la gestion des services via une interface web.