Votre site renvoie 502 Bad Gateway. Souvent il repasse au deuxième essai, puis retombe une heure plus tard. Parfois il ne tombe que sur le tableau de bord, ou seulement au moment de publier un article.
Ce guide traite le 502 et le 504, qui sont la même panne vue à deux instants différents. Il commence par une question que personne ne pose et qui vous fait gagner le plus de temps : qui a écrit cette page.
La page que vous avez sous les yeux désigne déjà un coupable
Un 502 nu, deux lignes, un titre 502 Bad Gateway et en dessous une signature du type nginx/1.24.0, pèse cent soixante-six octets. Cette page-là, c'est nginx qui l'a écrite, personne d'autre. Si vous voyez à la place une page mise en forme, avec des colonnes qui décrivent votre navigateur, un réseau intermédiaire et votre serveur, ce n'est plus votre serveur qui parle mais le service placé devant, Cloudflare le plus souvent. Certains mutualisés signent openresty, qui est encore du nginx sous un autre nom.
Cette lecture vous dit sur quelle pile technique vous êtes, avant d'ouvrir un ticket chez votre hébergeur. Nous l'avons mesuré sur un banc d'essai : un WordPress, un PHP-FPM, et deux serveurs web branchés dessus en parallèle. PHP-FPM arrêté, les deux interrogés dans la même seconde répondent ceci.
| serveur web | code renvoyé | poids | texte affiché |
|---|---|---|---|
Apache 2.4 avec proxy_fcgi |
503 | 390 o | Service Unavailable. The server is temporarily unable to service your request due to maintenance downtime or capacity problems |
nginx 1.24 avec fastcgi_pass |
502 | 166 o | 502 Bad Gateway, nginx/1.24.0 |
Même panne, même PHP mort, deux codes différents. L'essai a été refait avec un interlocuteur bien présent sur la socket mais incapable de parler le protocole FastCGI, pour vérifier que le résultat ne tenait pas à la façon dont le service s'était arrêté. Apache a de nouveau renvoyé 503. Apache 2.4 ne produit pas de 502 sur une panne de PHP-FPM, quelle qu'en soit la forme.
Le corollaire concerne une grande partie des sites français. Sur un mutualisé en Apache, ce qui est la configuration d'OVH et d'o2switch, un PHP tombé donne un 503, jamais un 502. La personne dans ce cas cherche « erreur 502 », ne trouve pas sa panne, et lit des pages qui parlent de nginx alors qu'elle n'en a pas. Si c'est votre situation, arrêtez-vous ici et passez au guide de l'erreur 503 : ni les gestes ni le premier tri n'y sont les mêmes.
En trente secondes
Rechargez la page une fois, et notez ce qui se passe. Si elle finit par s'afficher au deuxième ou au troisième essai, vous n'avez pas un problème de configuration mais un problème de capacité ou de délai. Un 502 permanent et un 502 intermittent ne se réparent pas au même endroit.
Regardez la signature de la page. nginx ou openresty : votre serveur web. Une page habillée aux couleurs d'un service de proxy : le 502 est peut-être émis avant votre serveur, et vos journaux resteront vides.
Repérez ce que vous faisiez. Le 502 qui tombe au clic sur « Publier », à l'enregistrement d'une page ou pendant une importation n'est pas le même que celui qui frappe l'accueil pour tout le monde. Le premier est une requête d'écriture trop longue, le second une saturation.
502 et 504, la même histoire à deux moments
Votre serveur web ne fabrique pas les pages WordPress : il transmet la demande à PHP et attend la réponse. Le 502 dit que PHP n'a pas répondu du tout : service arrêté, socket introuvable, processus mort en cours de route, ou plus un seul emplacement libre pour prendre la demande. Le 504 dit que PHP a bien été joint mais qu'il n'a pas fini à temps, et que le serveur web a coupé au bout du délai qu'il s'était donné. Même famille de causes, le temps en plus, et c'est pour ça que les deux codes alternent sur un site qui va mal.
Ni l'un ni l'autre ne signifie que WordPress est hors de cause. Sur les forums, la réponse réflexe est « c'est un problème serveur, appelez votre hébergeur ». Elle est fausse la plupart du temps : c'est le code de votre site qui a demandé au serveur un effort qu'il ne pouvait pas fournir.
Les causes, dans l'ordre où elles apparaissent vraiment
Ce qui suit vient de huit fils de discussion publics consacrés à un 502 sur WordPress, lus en entier, en français et en anglais. Trois seulement se concluent par une cause établie, ce qui est déjà une information : rien à l'écran ne dit ce qui s'est passé, et les gens abandonnent.
| Ce que vous observez | Ce que ça désigne |
|---|---|
| Le site passe au deuxième essai, en permanence ou par vagues | Pool PHP saturé, ou limite de processus simultanés atteinte |
| 502 au clic sur « Publier », à l'enregistrement, pendant une importation | Requête trop longue, le serveur web a coupé |
| 502 sur toutes les pages depuis une intervention sur le serveur | Chemin de socket ou de port qui ne coïncide plus |
502 seulement sur les adresses qui contiennent wp-admin |
Requêtes de fond de l'administration, ou proxy devant le site |
| 502 sur une seule page, toujours la même | Appel sortant refusé à l'autre bout |
| Coupures courtes qui reviennent tous les deux ou trois jours | Volume anormal de requêtes vers admin-ajax.php |
La bonne question n'est pas « qu'ai-je fait juste avant » mais « qu'est-ce qui a changé dans les vingt-quatre heures ». Le cache d'opcode garde en mémoire la version compilée des fichiers PHP : une modification faite la veille peut ne produire ses effets qu'au redémarrage du pool, la nuit suivante.
La réparation, cause par cause
Le pool PHP est saturé
C'est le cas du 502 qui passe au deuxième essai. Votre hébergeur vous alloue un nombre fixe de processus PHP simultanés. Quand ils sont tous occupés, la demande suivante n'a personne pour la prendre, et le serveur web répond 502 plutôt que de la faire attendre.
Le journal de PHP-FPM écrit alors une ligne qu'on ne peut confondre avec aucune autre :
WARNING: [pool www] server reached pm.max_children setting (5),
consider raising it
Sur un serveur que vous administrez, pm.max_children se règle dans le fichier du pool, généralement /etc/php/8.3/fpm/pool.d/www.conf. Montez la valeur par paliers en surveillant la mémoire : chaque processus PHP en consomme, et un pool trop généreux fait tomber la machine entière au lieu d'une page.
Sur un mutualisé, vous ne réglez rien : vous cherchez ce qui consomme les processus. Un fil du forum officiel documente une extension qui lançait une multitude de sous-processus à chaque exécution et atteignait la limite de quatre-vingts processus simultanés du compte. Le symptôme distinctif est que le site revient tout seul au bout de quelques minutes.
PHP a mis trop de temps
C'est le 504, et c'est aussi le 502 qui ne tombe qu'à l'écriture. Publier un article, enregistrer une page lourde, lancer une importation : ce sont des requêtes qui durent, et deux délais différents peuvent les couper.
Le premier est celui de PHP, max_execution_time. Quand c'est lui qui coupe, le journal de PHP-FPM nomme le script et la durée :
WARNING: [pool www] child 21755, script '/var/www/site/index.php'
(request: "POST /wp-admin/post.php") execution timed out (31.2 sec), terminating
Le second est celui du serveur web. Sous nginx, ce sont les directives fastcgi_read_timeout et proxy_read_timeout. Augmenter l'un sans l'autre ne sert à rien, le plus court des deux gagne toujours : c'est l'erreur de celui qui a monté max_execution_time à trois cents secondes et voit encore son 504 au bout de soixante.
Pour une importation ou une sauvegarde, la vraie réponse n'est pas d'allonger les délais mais de découper le travail par lots.
La socket n'est pas là où on la cherche
Ce cas ne concerne que les serveurs que vous administrez, et il produit un 502 franc, sur tout le site, immédiatement après une intervention ou une montée de version de PHP.
Le pool PHP-FPM écoute sur un chemin, par exemple /run/php/php8.3-fpm.sock, et le serveur web en interroge un autre, /var/run/php/php8.3-fpm.sock. Les deux se ressemblent assez pour qu'on les relise dix fois sans voir la différence. Le journal d'erreurs de nginx, lui, la voit tout de suite :
connect() to unix:/var/run/php/php8.3-fpm.sock failed
(2: No such file or directory) while connecting to upstream
Comparez la valeur de listen dans le fichier du pool et celle de fastcgi_pass dans le bloc serveur de nginx. Elles doivent être identiques au caractère près. Rechargez les deux services après correction, pas seulement nginx.
Un volume anormal de requêtes vers admin-ajax.php
Cette cause est absente du corpus français, et elle explique une famille entière de 502 qui reviennent par vagues sans que rien n'ait changé sur le site.
admin-ajax.php est le fichier par lequel WordPress parle au serveur en arrière-plan pendant que vous regardez une page. Certaines extensions s'en servent pour compter des affichages ou suivre une statistique, une fois par visiteur, parfois plusieurs. Sur un site un peu fréquenté, ça remplit le pool PHP en silence, et le site tombe quelques minutes tous les deux ou trois jours.
Le repérage se fait depuis votre navigateur, sans rien installer. Outils de développement, onglet Réseau, filtre XHR, puis chargez une page publique. Si admin-ajax.php apparaît alors que vous n'êtes pas connecté, regardez ce que la requête transporte : le nom de l'extension est presque toujours dans les paramètres. Beaucoup proposent un autre mode de suivi dans leurs réglages, ce qui règle le problème sans rien désinstaller.
Un appel sortant refusé à l'autre bout
Symptôme très reconnaissable : le site entier fonctionne, une seule page renvoie 502, toujours la même, et depuis une date précise.
Cette page exécute un script qui va chercher quelque chose ailleurs, un tarif ou un flux de données. Sur un mutualisé, votre site sort sur internet avec l'adresse IP partagée du cluster. Si le service distant a bloqué cette adresse, l'appel n'aboutit pas, le script attend, et votre serveur finit par couper. Un fil de la communauté OVH documente ce scénario, résolu quand le propriétaire du service distant a confirmé le blocage.
Identifiez quel service la page appelle, puis demandez à votre hébergeur l'adresse IP de sortie de votre hébergement pour la transmettre au service en question.
Le 502 vient du proxy, pas de votre serveur
Si votre site passe par un proxy ou un CDN, le 502 peut naître entre ce service et vous. Vos journaux serveur resteront alors vides, et c'est le signe le plus fiable qui soit : une panne bien réelle dont aucune trace n'existe chez vous.
Mettez le proxy en pause le temps de quelques requêtes, ou interrogez directement l'adresse IP de votre serveur. Si le site répond, la panne est devant. Si le 502 persiste, elle est derrière, et vous revenez aux causes précédentes.
Le cas particulier du 502 qui ne frappe que les adresses contenant wp-admin appartient à cette famille. Le tableau de bord envoie des requêtes de fond en continu, plus longues et plus lourdes que l'affichage d'une page publique. Si le site public tourne et que seul l'administration tombe, le guide de l'administration WordPress inaccessible traite la panne sous son bon angle.
Les journaux : où ils sont, et la ligne exacte à chercher
Toutes les pages du sujet disent « consultez vos logs ». Aucune ne dit lesquels, ni ce qu'on y cherche. C'est pourtant là que se joue la différence entre dix minutes et une soirée entière.
Il y a deux journaux, et sur un 502 c'est le second qui donne la réponse.
Le journal du serveur web vous dit qu'il n'a pas obtenu de réponse, et de quelle façon. Sous nginx, /var/log/nginx/error.log. Les lignes qui comptent :
connect() to unix:... failed (2: No such file or directory): PHP n'écoute pas là. Service arrêté, ou mauvais chemin.connect() to unix:... failed (11: Resource temporarily unavailable): PHP écoute mais la file d'attente est pleine. Pool saturé.recv() failed (104: Connection reset by peer) while reading response header from upstream: PHP a accepté la demande puis est mort en cours de route.upstream timed out (110: Connection timed out) while reading response header from upstream: c'est le 504.
Le journal de PHP-FPM vous dit pourquoi, et c'est celui que personne ne mentionne. Sur Debian ou Ubuntu il se trouve sous /var/log/php8.3-fpm.log, le numéro suivant votre version. Les lignes décisives commencent par WARNING: [pool www] et nomment le problème sans détour : server reached pm.max_children setting, execution timed out, ou child ... exited on signal 11 (SIGSEGV) quand un processus s'est écroulé.
Sur un mutualisé, vous n'avez ni l'un ni l'autre en accès direct. Le panneau expose en général un journal d'erreurs du compte, souvent un fichier error_log à la racine du site ou dans un dossier logs. S'il est vide, demandez au support les lignes correspondant à l'horaire exact d'un essai que vous venez de faire. Notez l'heure à la seconde avant de recharger la page. Cette précision change la qualité de la réponse du tout au tout.
La fausse piste qui coûte le plus de temps
Vider le cache du navigateur, essayer la navigation privée, redémarrer sa box, changer de serveur DNS. La vidéo la plus regardée du sujet consacre la moitié de son temps utile à ces gestes, et les articles français les reprennent en tête de liste.
Ces conseils s'adressent à un visiteur qui tombe sur un site en panne qui n'est pas le sien. Vous êtes le propriétaire. Le 502 est écrit par votre serveur, dans vos journaux, pour vos visiteurs, et aucun réglage de votre poste ne le fera disparaître. Le seul test client qui garde un intérêt tient en dix secondes : ouvrez le site depuis votre téléphone en réseau mobile. Il tombera aussi, et vous n'y revenez plus.
Deuxième perte de temps, désactiver toutes les extensions avant d'avoir lu quoi que ce soit. Sur un 502 par saturation ou par délai, ça ne dit rien : la panne dépend de la charge, pas d'un fichier fautif. Le journal tranche en une ligne.
Si rien n'a marché
Les journaux sont vides et la panne est réelle. Le 502 est émis avant votre serveur. Regardez du côté du proxy ou du CDN, et de la page d'état du service.
Le site tombe aux mêmes heures tous les jours. Pas une erreur de configuration, mais une limite de ressources atteinte à l'heure de pointe ou une tâche planifiée trop lourde. Un mutualisé qui ne suffit plus se change, il ne se règle pas.
Vous voyez une erreur 500 et non un 502. Le 500 veut dire que PHP a bien répondu, et qu'il a répondu une erreur. La procédure n'a rien à voir, le guide de l'erreur 500 la donne en entier.
Ce que nous ne faisons pas. Le forfait couvre la panne : remettre le site en ligne et vous dire ce qui l'a causé. Il ne couvre pas la reconstruction d'une mise en page abîmée dans un constructeur, ni la refonte d'un thème.
Si vous en êtes à chercher dans quel dossier votre hébergeur range ses journaux, l'intervention coûte moins cher que la soirée. La remise en service d'un WordPress en panne est à 149 € HT, remis en ligne ou remboursé.
Comment éviter que ça recommence
Repérez vos journaux à froid. Cherchez maintenant, site en état de marche, où votre hébergeur expose l'error_log du compte. Le jour de la panne, cette information vaut une heure.
Surveillez admin-ajax.php. Après chaque installation d'extension, ouvrez l'onglet Réseau sur une page publique et vérifiez qu'aucune requête de fond n'est apparue.
Sachez combien de processus PHP vous avez. La valeur est dans votre offre d'hébergement ou dans le panneau. Un site qui tourne en permanence à la limite tombera au premier pic de trafic.
Découpez les traitements longs plutôt que d'allonger les délais. Une importation ou une régénération de vignettes se lance par lots.
Questions fréquentes
Comment résoudre l'erreur 502 bad gateway ?
Rechargez la page. Si le site revient au deuxième essai, la cause est une saturation du pool PHP ou un délai dépassé, pas une erreur de configuration. Regardez ensuite qui signe la page d'erreur, nginx ou un proxy placé devant. Puis ouvrez les journaux : celui du serveur web dit de quelle façon PHP n'a pas répondu, celui de PHP-FPM dit pourquoi. Désactiver ses extensions à l'aveugle avant cette lecture ne mène nulle part sur ce code.
C'est quoi 502 Bad Gateway ?
Un code de réponse HTTP qui signifie que le serveur web n'a pas obtenu de réponse valable du service auquel il avait transmis la demande. Sur un WordPress, ce service est PHP. Le code ne dit rien de la cause : détailler la panne au visiteur reviendrait à exposer le fonctionnement interne du site.
Pourquoi mauvaise passerelle ?
« Mauvaise passerelle » est la traduction littérale de Bad Gateway, et elle prête à confusion. Il n'y a pas de passerelle défectueuse chez vous ni chez votre fournisseur d'accès. Le mot désigne le serveur web dans son rôle d'intermédiaire entre le visiteur et PHP.
C'est quoi erreur 504 ?
Le 504 dit que PHP a reçu la demande mais n'a pas fini dans le temps imparti, et que le serveur web a coupé. Même famille de causes que le 502, avec le temps en plus, et les deux codes alternent souvent sur un même site. Déclencheurs habituels : une importation, une sauvegarde, l'enregistrement d'une page très lourde.
Le 502 vient-il de WordPress ou du serveur ?
Le code est écrit par le serveur web, la cause est presque toujours dans le site. Une extension qui multiplie les requêtes de fond, un script qui attend un service distant, une page qui met une minute à s'enregistrer : le serveur web constate seulement que PHP n'a pas répondu. La réponse type des forums, « c'est un problème serveur, appelez votre hébergeur », fait perdre plusieurs jours à qui la suit.
J'ai un 502 chez OVH ou o2switch, est-ce le bon guide ?
Vérifiez d'abord ce que vous voyez. Ces hébergeurs servent les sites en Apache, et nous avons mesuré qu'Apache ne renvoie pas de 502 quand PHP tombe : il renvoie un 503. Un 502 chez eux vient d'autre chose, d'un service placé devant le site le plus souvent. Si c'est en réalité un 503 que vous avez, le guide de l'erreur 503 est le bon.