Erreur 502 WordPress : diagnostiquer le proxy et le serveur d’origine

Comprendre ce que le proxy n’a pas reçu

Votre site affiche « 502 Bad Gateway », parfois avec le nom de Nginx ou d’un service de diffusion. Un intermédiaire n’a pas obtenu une réponse valide du service auquel il s’adressait. Le numéro décrit cet échange défaillant ; il ne prouve pas que WordPress est corrompu ni que votre connexion personnelle est responsable.

Le proxy est un serveur qui reçoit la demande puis la transmet. L’origine désigne l’hébergement du site derrière cet intermédiaire. Il peut y avoir plusieurs relais : un service externe, le serveur web de l’hébergeur, puis le moteur PHP qui exécute WordPress. Une erreur sur une liaison peut remonter jusqu’au visiteur.

Le résultat recherché est de retrouver la liaison et la demande en cause, puis de corriger leur traitement. Une erreur 504 désigne un délai dépassé ; elle ne justifie pas exactement les mêmes conclusions. Gardez le code réellement observé, même si l’écran ressemble à celui d’un autre incident.

Préparez les accès et le retour sans perdre un traitement

Si le 502 suit un achat, un envoi ou un enregistrement, vérifiez d’abord son résultat côté application. Une réponse perdue peut arriver après une opération enregistrée. Pour le diagnostic, privilégiez une page de lecture et un brouillon sans publication. Copiez le travail non enregistré avant toute reconnexion.

Notez le domaine, l’heure et son fuseau, la dernière modification connue et les chemins touchés. Gardez une session utile ouverte. Avant un changement de composant, conservez une sauvegarde adaptée et son état d’activation ; avant une modification serveur, gardez le fichier et la valeur d’origine dans un dossier privé.

Les parcours demandent des accès différents : administration WordPress ou fichiers pour isoler un composant ; SSH avec droits de service pour PHP-FPM ; administration Nginx pour sa liaison. Les commandes serveur suivantes ne concernent pas un hébergement mutualisé sans ces droits. Vous pouvez néanmoins établir le relevé HTTP et transmettre une demande précise plutôt que réclamer un redémarrage général.

Repérez la requête 502 dans le navigateur

Accès requis : navigateur, sans ajout de composant. Le résultat attendu est d’identifier la page ou la ressource qui reçoit réellement 502. L’accueil en cache peut fonctionner alors qu’un traitement dynamique échoue. Une image visible ne valide donc pas la liaison vers PHP.

Cette observation ne modifie pas le site. Si un formulaire a échoué, observez les données déjà présentes dans Réseau au lieu de le renvoyer. Conservez uniquement les caractéristiques nécessaires ; un export complet peut contenir des cookies et des données privées.

Ouvrez une page publique de lecture connue. Dans le menu du navigateur, ouvrez les outils de développement, puis Réseau.
Rechargez cette page une fois et sélectionnez sa ligne Document. Relevez le statut, l’adresse finale et l’heure.
Si le Document répond normalement, repérez quelle autre ressource reçoit 502 et notez son domaine. Un service tiers exige un diagnostic séparé.
Dans les en-têtes de réponse, relevez un identifiant comme Ray ID lorsqu’il est présent, sans copier les secrets de session.
Comparez avec une seconde page publique puis une page d’administration accessible. Gardez les succès et les échecs dans le relevé.

Gardez une preuve HTTP avec curl si un terminal est disponible

Ce contrôle est facultatif et demande seulement curl installé sur votre ordinateur. Remplacez l’exemple par une page publique de lecture. Choisissez la ligne de votre système. L’option -q, placée en premier, ignore un éventuel fichier de configuration curl. La requête GET affiche les en-têtes et ne conserve pas le corps ; elle ne renvoie pas votre formulaire et n’utilise aucun identifiant.

Résultat attendu : statut de la première réponse et éventuel identifiant de requête. Un 301 ou 302 demande de regarder Location avant de tester la destination connue. Sans option de suivi, la première redirection reste visible. Un 502 avec curl et une réussite dans le navigateur peuvent aussi refléter un traitement de sécurité ou de cache différent.

Gardez les en-têtes privés, notamment Set-Cookie, et ne collez pas de cookies ou de mot de passe dans la commande. Aucun retour arrière n’est nécessaire. Si curl n’est pas disponible, le relevé du navigateur suffit pour continuer.

# macOS ou Linux
curl -q -sS -D - -o /dev/null "https://www.example.com/"
# Windows PowerShell : utiliser cette ligne à la place
curl.exe -q -sS -D - -o NUL "https://www.example.com/"

Choisissez l’intervention d’après le changement et les journaux

Le premier parcours convient si une mise à jour ou un composant précis précède l’échec, tandis qu’une partie de WordPress reste utilisable. Vous pouvez isoler ce changement avec l’administration ou les fichiers, de préférence sur copie si cela affecte les visiteurs. Un 502 seul ne suffit pas à désigner une extension.

Le deuxième concerne un serveur que vous administrez, lorsque les journaux désignent PHP-FPM arrêté ou défaillant. Il permet de consulter le service exact puis de remettre en route celui qui est réellement prévu. Il ne s’applique pas à une offre mutualisée sans SSH ni au simple titulaire d’un compte WordPress.

Le troisième répare une liaison Nginx vers PHP-FPM après une migration ou un changement de version, si les deux configurations ne désignent plus le même point de communication. Une connexion refusée ou un socket absent n’est pas un délai trop court. Gardez le message précis pour choisir ce parcours au lieu d’augmenter tous les timeouts.

Approche 1 : annulez le seul changement WordPress identifié

Accès requis : administrateur WordPress et sauvegarde adaptée au composant. Choisissez cette voie si une extension non indispensable vient d’être activée ou mise à jour et que le journal ou la chronologie la désigne. Pour une boutique ou une fonction essentielle, faites l’essai sur une copie protégée avec courriels et paiements neutralisés.

Résultat attendu : la même lecture ne produit plus 502 après isolement de ce seul composant. Cela confirme une piste, pas nécessairement un défaut intrinsèque : un conflit ou un manque de ressources peut intervenir. Si l’erreur reste identique, remettez l’état d’origine avant d’examiner un autre composant.

Ouvrez Extensions, puis Extensions installées. Notez le nom, la version et l’état de l’extension impliquée.
Vérifiez les effets d’une désactivation sur la fonction métier. Si l’essai peut être fait dans le contexte choisi, cliquez sur Désactiver pour cette seule extension.
Reprenez la page de lecture qui échouait, dans le même contexte et par le trajet normal du visiteur. Contrôlez son statut.
Si le 502 disparaît, conservez l’extension isolée sur la copie et vérifiez une correction ou une version fiable avec son éditeur avant retour en production.
Pour annuler un essai sans effet, cliquez sur Activer pour cette extension puis contrôlez le retour de sa fonction. N’installez pas un ZIP ancien provenant d’un site inconnu.

Sans tableau de bord, renommez seulement le dossier suspect

Accès requis : gestionnaire de fichiers ou SFTP autorisé. Cette voie sert à isoler une extension précisément identifiée lorsque WordPress ne s’ouvre plus. Elle affecte réellement la fonction du composant : pour une extension essentielle ou un multisite, faites préparer la portée par son responsable. Un service PHP arrêté ne sera pas réparé par ce renommage.

Résultat attendu : WordPress peut traiter la lecture sans charger ce composant. Si rien ne change, rendez aussitôt le nom d’origine. Si le test permet de retrouver l’administration, contrôlez l’état dans Extensions : remettre un dossier à son nom ne garantit pas sa réactivation après détection de son absence.

Dans les fichiers de la bonne installation, ouvrez wp-content/plugins, sauf chemin personnalisé connu. Notez le nom exact du seul dossier suspect.
Renommez ce dossier en ajoutant par exemple .isole au nom. Ne renommez pas tout plugins et ne supprimez aucun fichier.
Ouvrez une page de lecture puis l’administration. Notez si le 502 disparaît et conservez l’heure du test.
Pour annuler un essai sans effet, remettez le nom exact. Vérifiez ensuite le statut du composant dans l’administration dès qu’elle devient accessible.
Si le composant est impliqué, préparez sa réparation sur copie et son retour maîtrisé ; ne laissez pas une fonction métier désactivée sans l’avoir signalée.

Option : isolez un conflit de session avec Troubleshooting

Cette extension communautaire facultative est utile quand vous pouvez encore administrer WordPress et que l’échec se reproduit dans votre session. Sa fiche actuelle est publiée par Marius L. J. ; vérifiez les prérequis affichés avant installation. Elle tente d’isoler thèmes et extensions pour votre utilisateur. Elle ne sépare pas la base et ne neutralise pas les écritures, les courriels ou les paiements. Les extensions indispensables, dites mu-plugins, restent chargées et certains caches peuvent mal respecter le mode.

Résultat attendu : le même écran fonctionne dans un contexte simplifié, puis le composant déclencheur est retrouvé en les réintroduisant un à un. Cela ne prouve pas le comportement d’un visiteur anonyme et ne répare ni FPM ni un proxy. Privilégiez la copie de test si le cache ou une fonction sensible rendent l’essai incertain.

Dans Extensions > Ajouter une extension, cherchez Troubleshooting, contrôlez l’auteur et la compatibilité, puis installez et activez si l’essai est approprié.
Ouvrez Outils > Santé du site, puis l’onglet Troubleshooting ou Dépannage et activez son mode.
Reproduisez une lecture sans effet métier. Dans le menu Troubleshooting Mode de la barre d’administration, réintroduisez un composant à la fois et recommencez cette lecture.
Pour revenir, choisissez Disable Troubleshooting Mode dans ce menu ou dans l’écran du mode. Vérifiez ensuite la session normale et l’état réel des extensions.
Si un affichage reste altéré après sortie, contrôlez le cache concerné ; n’en déduisez pas qu’il faut réactiver globalement tous les composants.

Approche 2 : lisez l’état du service PHP-FPM sur votre serveur

Ce parcours demande SSH et des droits de consultation des services sur un serveur Linux utilisant systemd. PHP-FPM exécute les traitements PHP transmis par le serveur web. Commencez par lister les unités installées ; l’état enabled indique un démarrage configuré, pas que le service fonctionne actuellement.

L’exemple php8.3-fpm.service doit être remplacé par le service réellement prévu pour ce site. Ne choisissez pas une autre version uniquement parce qu’elle apparaît dans la liste. Les chemins et noms varient selon la distribution et les conteneurs ; sur une offre gérée sans ces accès, transmettez la demande au responsable avec votre relevé HTTP.

Résultat attendu : status indique active, inactive ou failed et le journal fournit le motif à l’heure de panne. Ces commandes sont en lecture seule. Si le service est actif, ne le redémarrez pas par réflexe : passez à la liaison et à la demande qui échoue. Gardez les journaux privés ; un service peut aussi écrire dans un fichier distinct.

systemctl list-unit-files 'php*-fpm.service'
systemctl status php8.3-fpm.service --no-pager
sudo journalctl -u php8.3-fpm.service --since "20 minutes ago" --no-pager

Remettez en route un service FPM qui devait fonctionner

Accès requis : administration de ce serveur et droit sudo sur l’unité identifiée. Ce cas est limité à un service prévu pour le site, arrêté après une intervention ou dont la cause d’échec a été corrigée. Ne démarrez pas toutes les versions PHP et ne réactivez pas un service volontairement arrêté pour maintenance.

Si le journal indique une erreur persistante de configuration, une bibliothèque absente ou un manque de ressources, corrigez d’abord cette cause et validez la configuration avec les outils de l’installation. Démarrer en boucle ne résout pas ce motif. La commande ci-dessous utilise encore php8.3-fpm.service comme exemple à remplacer par l’unité confirmée.

Résultat attendu : status indique active et la page dynamique répond normalement. La commande start ne modifie pas les fichiers de configuration. Si elle échoue, conservez le nouveau journal et arrêtez les tentatives répétées. Si vous aviez modifié une configuration pour corriger la cause, son retour doit utiliser la copie conservée et sa propre validation. Ne redémarrez pas tout le serveur pour tester ce seul service.

sudo systemctl start php8.3-fpm.service
systemctl status php8.3-fpm.service --no-pager
sudo journalctl -u php8.3-fpm.service --since "5 minutes ago" --no-pager

Approche 3 : alignez le point FastCGI de Nginx avec le bon pool PHP

Choisissez ce parcours si PHP-FPM fonctionne, mais que le journal Nginx signale un point de communication absent ou une connexion refusée après un changement. Accès requis : administration Nginx et connaissance du pool PHP associé au site. Un pool regroupe ses processus PHP et possède un réglage listen ; FastCGI désigne ici le protocole entre Nginx et ce pool.

Sur une organisation Debian ou Ubuntu classique, le pool peut être défini sous /etc/php/8.3/fpm/pool.d et le site Nginx sous /etc/nginx/sites-available. Ce sont des exemples : identifiez vos fichiers effectifs. La commande de lecture sudo nginx -T montre les fichiers chargés et les blocs server ; gardez cette sortie privée.

Résultat attendu : fastcgi_pass vise le socket ou le port réellement configuré pour ce site. L’exemple ci-dessous convient seulement si le listen du bon pool vaut précisément /run/php/php8.3-fpm.sock. N’appliquez pas ce chemin parce qu’il figure dans un tutoriel. Si le journal indique Permission denied plutôt qu’un chemin absent, faites corriger le groupe ou l’ACL prévu du socket ; ne passez pas ses droits à 777 et n’exposez jamais FPM sur Internet.

Dans la sortie privée de nginx -T, repérez le bloc server_name du domaine et sa directive fastcgi_pass.
Ouvrez le fichier du pool PHP effectivement associé à ce site et relevez listen. Si fastcgi_pass désigne un groupe upstream, examinez ce groupe au lieu de le remplacer arbitrairement.
Pour une liaison directe par socket, comparez les chemins exacts, conservez l’ancienne valeur et préparez uniquement la correction confirmée ci-dessous.

# Exemple seulement : dans le bloc PHP du bon site
fastcgi_pass unix:/run/php/php8.3-fpm.sock;

Appliquez la seule correction Nginx et gardez un retour immédiat

Accès requis : même administration serveur, sur un site dont vous avez identifié le fichier chargé. Remplacez le nom example.com ci-dessous par ce fichier réel et choisissez un nom de sauvegarde privé encore inutilisé. Cette opération suppose une configuration gérée manuellement ; sur un panneau qui la génère, corrigez sa source prévue au lieu d’un fichier régénéré.

Exécutez les commandes une à une. La sauvegarde va hors du répertoire public. Dans l’éditeur, modifiez uniquement fastcgi_pass selon le pool confirmé, puis enregistrez. Le test doit annoncer une syntaxe correcte et un test réussi avant de recharger Nginx ; sinon, corrigez ou restaurez sans rechargement. Le rechargement peut concerner les autres sites du même service : prévoyez la portée.

Résultat attendu : la lecture dynamique ne renvoie plus 502. Si elle échoue ou touche un autre site, remettez le fichier depuis la sauvegarde, relancez nginx -t puis rechargez seulement après son succès. Gardez le message exact ; augmenter un délai ne corrige pas un socket erroné.

sudo cp -p /etc/nginx/sites-available/example.com /root/example.com.nginx-avant-502
sudo nano /etc/nginx/sites-available/example.com
sudo nginx -t
# Seulement si le test précédent réussit :
sudo systemctl reload nginx

Quand Cloudflare affiche le 502, conservez la distinction origine-relais

Dans le navigateur, gardez l’URL précise et le Ray ID éventuel. Cloudflare décrit des erreurs issues de l’origine et d’autres provenant de son propre traitement. Son habillage aide au diagnostic selon les cas documentés, mais ne remplace pas le rapprochement avec les journaux et l’heure de la demande.

Si PHP ou la liaison du serveur a été réparé, testez d’abord par le trajet normal du domaine. Ne désactivez pas le proxy, ne changez pas les DNS et n’ouvrez pas l’origine pour vérifier. Une comparaison directe éventuelle doit être organisée par l’administrateur avec le bon nom d’hôte et les protections prévues.

Si la chaîne reste défaillante, transmettez au responsable du service l’identifiant et les résultats précis des contrôles précédents. Une compression invalide ou une réponse interrompue exige une correction de cette production de réponse, pas un allongement général des délais. Conservez la valeur précédente de tout réglage d’optimisation testé et annulez ce seul changement s’il n’aide pas.

Sur une offre gérée ou un multisite, respectez la portée des accès

Sur WordPress.com ou un hébergement administré sans accès système, ne lancez pas les commandes de VPS. Réalisez les contrôles HTTP et les manipulations WordPress autorisées, puis demandez au support de consulter le service et sa liaison. Précisez que l’accueil en cache fonctionne éventuellement alors qu’un écran dynamique échoue.

Dans un multisite, une extension partagée ou un service PHP peut concerner plusieurs sites. Le super administrateur doit valider la portée d’un isolement. Comparez quelques domaines touchés sans déclencher de charge ; ne renommez pas un composant réseau comme s’il n’appartenait qu’à votre site.

Si plusieurs origines servent le même domaine, un seul succès peut avoir atteint un autre nœud. Faites rapprocher les échecs de leurs journaux. Ne remplacez pas provisoirement la production par une préproduction publique contenant des données anciennes et des automatismes encore actifs.

Vérifiez la reprise sur les pages dynamiques et le parcours initial

Le résultat doit être la bonne réponse complète, pas seulement la disparition de l’étiquette 502. Une page en cache ne valide pas le traitement PHP. Pour un incident intermittent, reprenez aussi les moments et les demandes qui échouaient, avec une observation proportionnée plutôt qu’un test de charge.

Si une correction produit un nouvel échec, remettez seulement le composant ou le fichier modifié selon son parcours. Vérifiez les configurations serveur avant rechargement. Une restauration globale de base pourrait écraser des données récentes sans réparer la liaison.

Ouvrez les pages publiques relevées au départ et contrôlez statut, contenu et ressources.
Dans votre session habituelle, ouvrez un écran d’administration et le parcours dynamique autorisé.
Si un enregistrement doit être vérifié, utilisez un brouillon sans publication puis rouvrez-le ; ne testez pas un paiement ou un envoi réel.
Quittez tout mode de dépannage et contrôlez l’état réel des composants, ainsi qu’une visite déconnectée.
Notez l’heure et vérifiez les nouveaux journaux disponibles. Purgez seulement un cache dont une ancienne réponse a été confirmée.

Gardez la cause et les limites de la correction

Conservez le domaine, la requête, les heures et la correction appliquée. Distinguez le composant isolé, le service remis en route et la valeur de liaison corrigée. Un redémarrage suivi d’un succès ne démontre pas pourquoi le service s’était arrêté ; gardez cette incertitude si la cause n’a pas été établie.

Le dossier destiné au support doit contenir le message exact et ce qui fonctionne encore, sans cookies, identifiants ou journaux complets publiés. Pour une mémoire épuisée ou une capacité de processus atteinte, demandez les mesures de la fenêtre concernée. Augmenter le nombre de processus peut aggraver la consommation totale.

Avant la prochaine migration ou évolution PHP, vérifiez le pool choisi, sa disponibilité et la liaison du site avec un retour préparé. Retirez l’outil de diagnostic temporaire s’il n’est plus utile. Le prochain contrôle doit porter sur la liaison réellement modifiée, plutôt que répéter une désactivation générale des composants.

Vérifiez la page qui dépend réellement de l’origine

Dans le banc local, le relais sert une ressource statique et transmet la demande de page à un serveur PHP distinct. Au départ, la page répond 200 en accès direct et en passant par le relais. Après l’arrêt du serveur PHP, la connexion directe est refusée et le relais répond 502 pour la page. Le fichier statique répond encore 200. Après redémarrage de l’origine, la page dynamique répond de nouveau 200 sur les deux trajets et affiche son repère initial.

Si vous avez uniquement le navigateur, choisissez une lecture dynamique connue sur le site et une ressource statique que cette page charge habituellement. Dans le panneau Réseau, relevez séparément le statut de la demande de document et celui de la ressource. Gardez l’heure et le chemin qui échoue. Si une page peut être servie depuis un cache, notez aussi les indices disponibles dans les en-têtes et l’état connecté ou déconnecté. Le 200 de la ressource fournit un point de comparaison pour le support. La confirmation de la couche en défaut demande ensuite le journal du relais ou de l’origine.

Rapprochez les observations selon l’accès dont vous disposez

Avec le tableau de bord WordPress, vérifiez d’abord si le problème suit une action ou un écran précis. Une lecture sûre dans une session de dépannage peut aider à isoler un composant si le site charge encore PHP. Quittez le mode dès la comparaison terminée, puis vérifiez la session normale. Si toutes les demandes dynamiques échouent, passez au contrôle de la liaison entre le serveur web et le service d’exécution ou transmettez le relevé à l’hébergeur.

Avec l’accès système autorisé, recherchez à l’heure relevée la ligne correspondant à la demande en échec. Si le journal signale un refus de connexion vers le service configuré, vérifiez l’état de ce service et le point de connexion qu’il écoute. Consultez la configuration du vhost qui répond réellement et rapprochez les chemins ou les ports relevés. Le banc utilise une origine HTTP sur la boucle locale. Pour un socket FastCGI, utilisez le journal et les commandes de consultation de PHP-FPM décrites dans ce guide.

En hébergement géré, demandez au support de corréler le statut observé avec la requête correspondante côté proxy et côté origine. Joignez l’heure avec son fuseau, le chemin, le statut de la ressource statique et l’identifiant de requête s’il est disponible. Le retour du support doit permettre de savoir quelle liaison ou quel service a échoué avant de choisir une manipulation WordPress.

Rejouez le même contrôle après la correction

Après une réparation autorisée, contrôlez d’abord la même page dynamique depuis le trajet normal du site. Vérifiez le contenu attendu en plus du statut. Si l’écran concerné enregistre des données, commencez par une lecture et vérifiez ensuite sur la copie avec les données prévues. Rouvrez aussi une page qui dépend du même service pour confirmer que la reprise dépasse la seule adresse testée.

Si vous avez modifié le routage et que la requête reste en échec, restaurez la configuration sauvegardée, faites valider sa syntaxe puis rechargez-la comme prévu. Reprenez le relevé sur le même chemin. Dans la recette, le retour à l’état normal repose sur le redémarrage du seul service d’origine et sur la comparaison des deux réponses dynamiques avec leur état initial.

Notre méthode éditoriale