502 Bad Gateway: was hinter dem Proxy kaputt ist und wie Sie es finden

Wer einen 502 zurückgibt, und warum

RFC 9110 definiert 502 für einen Server, der als Gateway oder Proxy fungiert und eine ungültige Antwort von einem eingehenden Server erhalten hat, den er beim Versuch, die Anfrage zu erfüllen, kontaktiert hat. Jeder moderne Stack hat mindestens eine solche Station: nginx oder Apache vor einem Anwendungsserver, ein Load Balancer vor einer Serverflotte, ein CDN vor Ihrem Ursprungsserver, oder alle drei.

Diese Schichtung ist der Schlüssel zum Lesen eines 502. Die Komponente, die geantwortet hat, ist gesund genug, um eine Fehlerseite zu erzeugen. Die Komponente dahinter ist es nicht. Ein 502 teilt Ihren Stack also immer in eine funktionierende und eine defekte Hälfte, und Ihre Aufgabe ist es herauszufinden, wo die Grenze liegt.

Seine Nachbarn sagen etwas Konkreteres. Ein 504 Gateway Timeout bedeutet, dass das Backend erreichbar, aber zu langsam war. Ein 500 bedeutet, dass das Backend selbst lief und einen Fehler geworfen hat. Ein 502 bedeutet, dass das Backend eine schlechte Antwort gegeben hat oder gar keine. Der vollständige Vergleich steht in der 5xx-Übersicht.

Häufige Ursachen

• Der Backend-Prozess läuft nicht. Ein abgestürzter App-Server, ein gestoppter PHP-FPM-Pool, ein Container, der beendet wurde oder seinen Health-Check nicht bestanden hat. Der Proxy verbindet sich mit einem Port, an dem niemand lauscht.
• Das Backend ist mitten in der Anfrage abgestürzt. Ein Out-of-Memory-Kill oder ein Segmentation Fault schließt die Verbindung, bevor die Antwort-Header vollständig sind.
• Falsche Upstream-Adresse oder falscher Port. Eine Konfiguration, die nach einer Änderung noch auf den alten Port zeigt, oder auf einen Host, der nicht mehr auflöst.
• Protokoll-Fehlanpassung. Der Proxy spricht reines HTTP mit einem Port, der TLS erwartet, oder umgekehrt. Die Bytes sind nicht parsbar, der Proxy erklärt die Antwort also für ungültig.
• Antwort-Header zu groß. Ein übergroßes Cookie oder ein ungewöhnlich langer Header übersteigt den Puffer des Proxys, und die Antwort wird abgelehnt statt weitergereicht.
• Keep-Alive-Fehlanpassung. Der Proxy verwendet eine untätige Verbindung erneut, die das Backend bereits geschlossen hat, was vereinzelte 502er unter sonst normaler Last erzeugt.
• Neustarts und Deploys. Jedes Zeitfenster, in dem der alte Prozess gestoppt hat und der neue noch keine Verbindungen annimmt.
• Alle Backends ungesund. Ein Load Balancer ohne einen einzigen bestehenden Health-Check hat nirgendwohin, die Anfrage zu senden.

Das Proxy-Protokoll lesen, was die Untersuchung meist beendet

Der Statuscode ist generisch, aber die Protokollzeile des Proxys ist konkret. Bei nginx sind das die Meldungen, die man erkennen sollte:

[error] connect() failed (111: Connection refused) while connecting to upstream,
        upstream: "http://127.0.0.1:8080/"

[error] upstream prematurely closed connection while reading response header
        from upstream

[error] recv() failed (104: Connection reset by peer) while reading response
        header from upstream

[error] upstream sent too big header while reading response header from upstream

[error] no live upstreams while connecting to upstream

Jede zeigt auf etwas anderes:

• connect() failed (111: Connection refused). Auf dieser Adresse und diesem Port lauscht niemand. Das Backend ist gestoppt, an eine andere Schnittstelle gebunden, oder auf einem anderen Port, als die Konfiguration sagt.
• upstream prematurely closed connection. Das Backend hat die Anfrage angenommen und ist dann gestorben oder hat aufgelegt, bevor die Antwort fertig war. Suchen Sie nach Abstürzen, Out-of-Memory-Kills oder einem Worker-Timeout innerhalb der Anwendung, nicht bei nginx.
• connection reset by peer. Ähnlich, aber die Verbindung wurde aktiv zurückgesetzt. Oft eine Firewall dazwischen, oder ein Backend, das eine gepoolte Verbindung geschlossen hat, die der Proxy noch für offen hielt.
• upstream sent too big header. Ein Puffergrößenproblem im Proxy, kein Fehler im Backend. Die Antwort ist gültig, aber größer, als der Proxy konfiguriert ist zu fassen.
• no live upstreams. Health-Checks haben jedes Backend als nicht erreichbar markiert.

So beheben Sie es

1. Testen Sie das Backend direkt, am Proxy vorbei. Fragen Sie vom Proxy-Host aus die Upstream-Adresse selbst ab:

   curl -sS -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8080/

   Ein 200 hier bei einem 502 auf der öffentlichen URL bedeutet, dass der Fehler in der Proxy-Konfiguration oder der Verbindung zwischen beiden liegt. Eine abgelehnte Verbindung bedeutet, dass das Backend tatsächlich nicht erreichbar ist.
2. Prüfen Sie, ob das Backend läuft und lauscht, auf der Adresse, die der Proxy erwartet. Eine Bindung an 127.0.0.1, während der Proxy eine Containeradresse anwählt, ist eine häufige Ursache.
3. Lesen Sie das Fehlerprotokoll des Proxys und gleichen Sie die Meldung mit der obigen Liste ab, bevor Sie irgendeine Konfiguration ändern.
4. Lesen Sie dann das Backend-Protokoll. Ein Absturz, ein Out-of-Memory-Kill oder ein Worker-Timeout zur selben Sekunde bestätigt den Fall "prematurely closed". Stille deutet zurück auf Konnektivität.
5. Verifizieren Sie Upstream-Adresse, Port und Schema in der Proxy-Konfiguration, besonders nach einer Migration oder einem Container-Neuaufbau.
6. Erhöhen Sie die Header-Puffer des Proxys, falls das Protokoll sagt, der Header sei zu groß gewesen, und finden Sie separat heraus, warum der Header gewachsen ist.
7. Lassen Sie Deploys überlappen. Starten Sie den neuen Prozess, warten Sie, bis er einen Health-Check besteht, dann leeren Sie den alten und stoppen ihn. Health-gegatete Rolling Updates beseitigen das Neustartfenster, das Deploy-Zeit-502er verursacht, vollständig.

Einen 502 erkennen, der zwanzig Sekunden dauert

Deploy-Zeit- und Crash-Loop-502er sind kurz. Ein Backend startet neu, wirft zwanzig Sekunden lang Fehler und erholt sich, bis also jemand nachschaut, ist die Website in Ordnung, und es gibt nichts mehr zu sehen. Eine fortlaufend laufende geplante HTTP-Prüfung zeichnet diese Fenster mit Zeitstempeln auf, was aus "heute Morgen war es kurz komisch" ein Muster macht, das Sie mit Deploys und Neustarts korrelieren können. Ein 502 kann auch von einem CDN-Edge kommen statt von Ihrem Ursprungsserver, die Prüfung aus mehreren Regionen unterscheidet also einen globalen Backend-Ausfall von einem Edge-Problem, das nur einen Teil Ihres Traffics betrifft, wofür verteiltes Verfügbarkeits-Monitoring da ist.