Ein 502 Bad Gateway bedeutet, dass ein Server, der als Gateway oder Proxy arbeitet, vom Server dahinter eine ungültige Antwort erhalten hat. Der Besucher hat etwas erreicht, meist nginx, Apache, einen Load Balancer oder ein CDN, aber diese Schicht hat von Ihrer Anwendung keine ordentliche Antwort bekommen. Die Anwendung ist abgestürzt, startet gerade neu, lauscht an einer anderen Adresse oder hat die Verbindung mittendrin geschlossen.
Ein 502 ist also eine Meldung über zwei Server, nicht über einen. Dieser Leitfaden zeigt, wie Sie erkennen, welche Schicht ihn zurückgegeben hat, wie Sie die üblichen Ursachen beheben und wie Sie vom nächsten 502 erfahren, bevor Ihre Kunden es tun.
Was ein 502 Ihnen sagt
Die meisten Websites haben mindestens zwei Schichten zwischen Besucher und Code. Ein CDN oder Load Balancer sitzt davor, ein Webserver wie nginx nimmt die Verbindung an, und ein Anwendungsprozess wie PHP-FPM, Node.js, Gunicorn oder ein Java-Server erstellt die Seite. Jede Schicht leitet die Anfrage an die nächste weiter und gibt die Antwort zurück.
Ein 502 entsteht, wenn eine dieser Schichten eine Anfrage weiterleitet und nichts Brauchbares zurückbekommt. Zum Vergleich die anderen Gateway-Fehler:
502 Bad Gateway: Der Upstream-Server hat ungültig geantwortet, die Verbindung zurückgesetzt oder abgelehnt.
503 Service Unavailable: Der Dienst ist überlastet, in Wartung oder hat keinen funktionsfähigen Server, an den er die Anfrage schicken kann.
504 Gateway Timeout: Der Upstream-Server hat nicht rechtzeitig geantwortet.
Ein 502 heißt also meist „kaputt oder läuft nicht“, ein 504 meist „langsam“. Unser Spickzettel zu HTTP-Statuscodes listet die übrigen Codes der Familie, und der Leitfaden zu 503-Fehlern behandelt Überlast und Wartung.
Die Schicht finden, die den 502 zurückgegeben hat
Bevor Sie etwas ändern, finden Sie heraus, wer geantwortet hat. Fehlerseite und Response-Header sagen es meist direkt:
curl -sI https://www.example.com/checkout
HTTP/2 502
server: cloudflare
cf-ray: 8d2f1c3a5b7e4a21-ARN
server: cloudflare mit einer Cloudflare-Fehlerseite, die Ihren Host nennt: Cloudflare hat Ihren Origin erreicht, und der Origin ist gescheitert.
server: nginx oder Apache mit einer schlichten Fehlerseite: Ihr eigener Webserver hat die Anwendung dahinter nicht erreicht.
server: awselb/2.0 oder ein anderer Load Balancer: Der Load Balancer hat von keinem Ziel eine gültige Antwort bekommen oder von dem, das er ausgewählt hat.
Vergleichen Sie dann mit einer Anfrage, die die äußere Schicht umgeht. Schicken Sie sie direkt an den Origin oder an den Port der Anwendung auf dem Server selbst:
curl -sI –resolve www.example.com:443:203.0.113.10 https://www.example.com/checkout
curl -sI http://127.0.0.1:3000/checkout
Antwortet die Anwendung lokal, aber nicht über den Proxy, prüfen Sie die Konfiguration des Proxys. Antwortet sie auch lokal nicht, liegt das Problem bei der Anwendung.
Häufige Ursachen und wie Sie sie beheben
Der Anwendungsprozess ist abgestürzt oder startet neu
Die häufigste Ursache. Dem Prozess hinter dem Proxy ist der Speicher ausgegangen, er ist an einer unbehandelten Exception gescheitert oder wurde beendet, und der Proxy hat niemanden mehr, mit dem er sprechen kann. nginx protokolliert das unmissverständlich:
connect() failed (111: Connection refused) while connecting to upstream,
upstream: „http://127.0.0.1:3000/checkout“
Prüfen Sie, ob der Prozess läuft und warum er angehalten hat:
systemctl status myapp
journalctl -u myapp –since „30 min ago“
dmesg -T | grep -i „killed process“
Eine Zeile vom Out-of-Memory-Killer des Kernels bedeutet, dass dem Server der Arbeitsspeicher ausgegangen ist. Ein Neustart bringt die Website zurück, die eigentliche Lösung ist aber mehr Speicher, weniger Worker oder ein gefundenes und behobenes Speicherleck. Sorgen Sie dafür, dass der Dienst nach einem Absturz von selbst neu startet, etwa mit Restart=on-failure in seiner systemd-Unit.
PHP-FPM läuft nicht oder hat keine freien Worker
Auf PHP-Websites gibt nginx Anfragen über einen Socket oder Port an PHP-FPM weiter. Ist PHP-FPM gestoppt, der Socket-Pfad falsch oder sperren die Berechtigungen des Sockets nginx aus, liefert jede PHP-Seite 502:
connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory)
Diese Meldung folgt meist auf ein PHP-Upgrade: nginx zeigt noch auf den Socket der alten Version. Richten Sie fastcgi_pass auf den neuen Socket und laden Sie nginx neu. Steht im Log stattdessen server reached pm.max_children, sind alle Worker beschäftigt, oft weil sie auf eine langsame Datenbank oder eine externe API warten. Erhöhen Sie das Limit nur, wenn der Server Speicher übrig hat; andernfalls finden Sie heraus, was die Worker blockiert.
Falsche Upstream-Adresse oder falscher Port
Nach einer Migration, einem Container-Rebuild oder einem Portwechsel leitet der Proxy womöglich noch an die alte Adresse weiter. Das Error-Log zeigt die Adresse, die er versucht hat. Vergleichen Sie sie damit, wo die Anwendung tatsächlich lauscht:
ss -ltnp | grep -E ‚:(3000|8000|9000)‘
Unter Docker und Kubernetes ist die Ursache oft ein Service-Name, der nicht mehr aufgelöst wird, ein Container, der innerhalb des Containers auf 127.0.0.1 statt auf 0.0.0.0 lauscht, oder ein Readiness-Check, der jeden Pod als nicht bereit markiert.
Der Upstream hat die Verbindung zu früh geschlossen
upstream prematurely closed connection while reading response header bedeutet, dass die Anwendung die Anfrage angenommen und dann aufgelegt hat. Typische Gründe sind ein Absturz mitten in der Anfrage, ein Worker, der wegen Überschreitung seines eigenen Zeitlimits beendet wurde, etwa Gunicorns –timeout oder PHPs max_execution_time, und Keep-alive-Verbindungen, die die Anwendung früher schließt, als der Proxy erwartet. Stimmen Sie die Timeouts so ab, dass der Proxy etwas länger wartet als die Anwendung, nie umgekehrt, und prüfen Sie, welche Anfragen langsam genug sind, um das Limit zu erreichen.
Zu große Response-Header
Große Cookies oder viele Set-Cookie-Header können den Puffer überschreiten, den nginx für die Response-Header des Upstreams vorsieht. nginx protokolliert dann upstream sent too big header while reading response header from upstream und gibt 502 zurück. Erhöhen Sie die Puffer mit Bedacht:
proxy_buffer_size 16k;
proxy_buffers 8 16k;
# for PHP-FPM
fastcgi_buffer_size 32k;
fastcgi_buffers 8 16k;
Finden Sie dann heraus, warum die Header gewachsen sind. Ein Cookie, das bei jedem Besuch größer wird, ist ein Bug, den es sich zu beheben lohnt.
Das CDN erreicht Ihren Origin nicht
Gibt ein CDN oder Load Balancer 502 zurück, prüfen Sie, was zwischen ihm und Ihrem Server liegt. Eine Firewall, die die Adressbereiche des CDN blockiert, ein Origin-Zertifikat, das das CDN nicht akzeptiert, ein Origin, der nur HTTP/1.0 spricht oder Verbindungen zu schnell schließt, oder ein DNS-Eintrag, der auf einen alten Server zeigt: Alles endet gleich. Testen Sie den Origin wie oben gezeigt direkt und prüfen Sie Firewall und TLS-Einstellungen auf beiden Seiten.
502er während Deploys
Treten 502er jeweils zehn oder zwanzig Sekunden lang auf, und immer rund um ein Release, verursacht der Deploy sie selbst. Der alte Prozess stoppt, der neue braucht ein paar Sekunden zum Starten, und jede Anfrage dazwischen scheitert. Die Lösung ist eine Release-Reihenfolge, bei der immer etwas bereit ist zu antworten:
Starten Sie die neue Version neben der alten.
Warten Sie, bis ihr Health Check besteht. Unser Leitfaden zum Aufbau eines Health-Check-Endpunkts zeigt, was dieser Check testen sollte.
Leiten Sie den Traffic auf die neue Version um.
Lassen Sie die alte Version ihre laufenden Anfragen abarbeiten und stoppen Sie sie dann.
Prozessmanager und Orchestratoren unterstützen das als Rolling- oder Zero-Downtime-Reload. Nutzen Sie das statt eines einfachen Neustarts.
Wie Monitoring 502er erkennt
Ein 502 ist oft kurz. Ein Deploy verursacht zwanzig Sekunden Fehler, ein Worker stürzt ab und startet neu, ein Cache verbirgt das Problem für die meisten Besucher. Wenn jemand die Website öffnet, funktioniert sie wieder, aber ein Kunde mitten im Checkout hat den Fehler gesehen.
Ein Uptime-Monitor ruft Ihre Seiten nach Zeitplan auf und speichert Statuscode und Antwortzeit jedes Checks. Ein 502 ist ein fehlgeschlagener Check. Entscheidend ist, was danach passiert:
Den Fehler bestätigen. Eine einzelne fehlgeschlagene Anfrage kann ein Ausreißer sein. Uptimecheck prüft bis zu jede Minute aus Stockholm, London und New York und bestätigt jeden Fehler von einem zweiten Standort aus, bevor ein Vorfall eröffnet wird, damit ein einmaliger Verbindungsabbruch niemanden weckt.
Die Belege zeigen. Der Vorfall enthält die fehlerhafte Antwort, Sie sehen also Statuscode, server-Header und Fehlerseite sowie einen Screenshot dessen, was Besucher gesehen haben. Hat der Server gar nicht geantwortet, bekommen Sie stattdessen den Netzwerkpfad.
Die richtigen Leute erreichen. Alarme gehen per E-Mail, Slack, Microsoft Teams, PagerDuty, Webhooks und über die anderen Alarmkanäle, die Ihr Team nutzt.
Überwachen Sie mehr als die Startseite. Die Startseite wird oft von einem CDN gecacht und funktioniert weiter, während Checkout, Login und API 502 liefern. Richten Sie Uptime-Monitore für die Seiten ein, die Geld verdienen, und API-Monitore für die Endpunkte, die Ihre Apps aufrufen. Kommt der 502 von einer Anwendung, der der Speicher ausgegangen ist, zeigt Server-Monitoring die Speicherkurve neben dem Ausfall.
Checkliste für 502-Fehler
Lesen Sie den server-Header und die Fehlerseite, um zu sehen, welche Schicht den 502 zurückgegeben hat.
Rufen Sie Origin und Anwendungsport direkt auf, um das Problem einzugrenzen.
Lesen Sie das Error-Log des Proxys zum selben Zeitstempel: abgelehnt, zu früh geschlossen oder zu großer Header.
Prüfen Sie, ob der Anwendungsprozess läuft, und falls nicht, warum er angehalten hat.
Vergleichen Sie Upstream-Adresse, Socket und Port damit, wo die Anwendung lauscht.
Stimmen Sie die Timeouts so ab, dass der Proxy länger wartet als die Anwendung.
Starten Sie beim Deploy die neue Version, bevor Sie die alte stoppen.
Überwachen Sie wichtige Seiten und Endpunkte jede Minute und bestätigen Sie jeden Fehler, bevor alarmiert wird.