HTTP Statuscode 502: Bad Gateway lesen

Der HTTP-Statuscode 502 kommt nie von der Anwendung selbst. Er kommt von einer Instanz davor.

RFC 9110 definiert 502 „Bad Gateway" für den Fall, dass ein Server, der als Gateway oder Proxy arbeitet, von dem vorgelagerten Server eine ungültige Antwort erhalten hat. Damit steht schon in der Definition die wichtigste Information: Es gibt mindestens zwei Beteiligte, und derjenige, der den Fehler meldet, ist nicht derjenige, der ihn verursacht hat.

Wer hier mit wem spricht#

Eine typische Auslieferungskette besteht heute aus mehreren Schichten. Ein CDN oder ein Loadbalancer nimmt die Anfrage entgegen, reicht sie an den Webserver weiter, dieser gibt dynamische Anfragen an einen Anwendungsprozess ab — bei PHP an PHP-FPM, bei Node oder Python an einen eigenen Dienst hinter einem Socket oder Port.

Jede dieser Übergaben ist eine Stelle, an der eine 502 entstehen kann. Der Proxy erwartet eine wohlgeformte HTTP- oder FastCGI-Antwort. Bekommt er stattdessen nichts, eine abgeschnittene Antwort, unsinnige Kopfzeilen oder eine geschlossene Verbindung, hat er keine Möglichkeit, das weiterzureichen. Er antwortet mit 502.

Daraus folgt die erste praktische Regel: Die Fehlerseite zeigt immer die äußerste Schicht. Steht ein CDN davor, stammt die sichtbare Seite vom CDN, und der eigentliche Vorgang liegt eine oder zwei Ebenen tiefer.

Abgrenzung zu 500 und 504#

Die drei Codes beschreiben unterschiedliche Zustände, auch wenn der Besucher jeweils nur eine kaputte Seite sieht.

• 500 — die Anwendung hat einen Fehler gemeldet, aber sauber geantwortet. Die Antwort ist gültig, ihr Inhalt ist eine Fehlermeldung.
• 502 — es kam gar keine verwertbare Antwort. Die Verbindung brach ab oder das Gegenüber war nicht ansprechbar.
• 504 — es kam keine Antwort innerhalb der eingeräumten Zeit. Der Upstream lebt möglicherweise noch und rechnet.

Der Unterschied zwischen 502 und 504 ist deshalb wichtig, weil er zwei verschiedene Untersuchungen nach sich zieht. Eine 502 deutet auf einen Prozess, der abgestürzt, überlastet oder nicht erreichbar ist. Eine 504 deutet auf etwas, das zu lange dauert, meist im Datenzugriff.

Eine Besonderheit bei nginx mit PHP-FPM: Stirbt der PHP-Worker mitten in der Verarbeitung — durch Speicherüberschreitung, ein Segmentation Fault in einer Erweiterung oder einen Kill durch den OOM-Killer des Systems —, sieht nginx eine abgebrochene FastCGI-Verbindung. Der Besucher bekommt 502, obwohl die Ursache ein gewöhnlicher Fehler in der Anwendung ist, wie er sonst zu einer 500 führen würde.

Was der Betreiber prüft#

Die Reihenfolge ist nicht beliebig. Von außen nach innen ist sie am schnellsten.

1. Läuft der Upstream-Dienst überhaupt? Bei PHP-FPM, Node oder Gunicorn zuerst der Prozessstatus. Ist der Dienst gestoppt oder beim Neustart hängengeblieben, erklärt das jede weitere Beobachtung.

``bash systemctl status php-fpm ``

2. Stimmt die Adresse? In der nginx-Konfiguration steht bei fastcgi_pass oder proxy_pass ein Socketpfad oder ein Port. Nach einem Update der PHP-Version ändert sich dieser Pfad regelmäßig, während die alte Zeile im virtuellen Host stehen bleibt. Das Fehlerlog nennt den Fall deutlich: „connect() to unix:/... failed (No such file or directory)".

3. Was steht im Fehlerlog des Proxys? Bei nginx /var/log/nginx/error.log. Die Einträge unterscheiden sauber zwischen „Connection refused", „no live upstreams", „recv() failed" und „upstream prematurely closed connection". Jede dieser Formulierungen zeigt in eine andere Richtung.

4. Sind die Worker ausgelastet? PHP-FPM protokolliert bei erschöpftem Prozesspool einen Hinweis auf max_children. Unter Last stehen neue Anfragen dann in der Warteschlange, bis der Dienst die Verbindung ablehnt. Das Ergebnis ist eine 502, die kommt und geht, statt dauerhaft zu bestehen.

5. Passen die Puffergrößen? Antworten mit ungewöhnlich großen Kopfzeilen, etwa durch viele oder sehr lange Cookies, überschreiten mitunter die Puffer des Proxys. Im Log erscheint dann ein Hinweis auf „upstream sent too big header".

6. Log der Anwendung. Erst danach lohnt der Blick in error_log oder debug.log der Anwendung, um den fatalen Fehler zu finden, der den Prozess beendet hat.

Wenn 502 sporadisch auftritt#

Eine dauerhafte 502 ist meist ein Konfigurationsfehler und schnell gefunden. Eine sporadische ist die unangenehmere Variante, weil sie fast immer mit Last zusammenhängt: zu wenige Worker, ein Neustartzyklus des Anwendungsdienstes, ein Speicherlimit, das nur bei bestimmten Anfragen erreicht wird.

Auffällig ist der Fall, in dem 502-Antworten in Wellen kommen, ohne dass die Besucherzahl steigt. Dann lohnt der Blick auf die Zugriffsprotokolle: Automatisierter Traffic auf teure Endpunkte erzeugt dieselbe Wirkung wie ein Ansturm echter Nutzer. Wenn dabei Anfragemuster auf Anmelde- oder Suchseiten auffallen, gehört das in eine andere Untersuchung — woran man eine gehackte Website erkennt, beschreibt die Anzeichen. Was ein Host nach außen an Kopfzeilen und Diensten preisgibt, zeigt der Security-Scan.