nginx liefert 504 Gateway Timeout? Der Upstream antwortet nicht rechtzeitig, bevor nginx aufgibt. So findest du die Ursache und setzt Timeouts sinnvoll.
Aufwand:
ca. 20 Min.
Voraussetzung:
Root- bzw. sudo-Zugriff auf den Server
Gilt für:
nginx als Reverse-Proxy bzw. FastCGI-Gateway
Das Symptom
Die Seite lädt und lädt, dann steht im Browser nüchtern 504 Gateway Timeout.
Oft trifft es nur einzelne, schwere Aktionen – einen Export, einen Report, einen
Login unter Last – während der Rest der Seite tadellos funktioniert. nginx läuft,
der Dienst dahinter läuft auch, und trotzdem bricht ausgerechnet die eine
wichtige Anfrage nach etwa einer Minute ab.
Die „Layer 8“-Wahrheit
504 ist nicht die Klage, dass der Upstream tot sei – das wäre ein 502. 504 heißt:
Der Dienst dahinter lebt, er ist nur zu langsam. nginx steht als Vermittler davor,
reicht die Anfrage weiter und wartet – standardmäßig 60 Sekunden. Kommt in dieser
Zeit keine Antwort, gibt nginx auf und meldet ehrlich, dass der Gateway in ein
Timeout gelaufen ist. Der Reflex, nginx neu zu starten oder einfach den Timeout
zu verdreifachen, behandelt darum das falsche Ende: Der Engpass sitzt eine Etage
tiefer, in der Anwendung. Fast immer steckt eine lahme Datenbankabfrage dahinter,
ein externer Dienst, der selbst hängt, oder schlicht kein freier Worker. Das
Errorlog nennt die Richtung, ein direkter Aufruf des Upstreams mit Zeitmessung den
Rest. Wer die langsame Wurzel findet, braucht den höheren Timeout gar nicht erst.
Die echte, verifizierte Lösung
1000 % faktenbasiert. Jeder Befehl ist real, jeder Pfad existiert. Schritt für Schritt:
1.
Das Errorlog lesen
Zuerst die genaue Meldung holen. Bei 504 steht dort typischerweise „upstream timed out (110: Connection timed out) while reading response header from upstream“ – das trennt Timeout sauber von einem toten Dienst:
tail -n 50 /var/log/nginx/error.log
2.
Den Upstream direkt und mit Zeitmessung ansprechen
nginx umgehen und den Dienst direkt anfragen, um zu sehen, wie lange er wirklich braucht. Das gilt nur für Dienste, die HTTP sprechen – etwa Gunicorn oder Node auf einem lokalen Port. Antwortet er schnell, liegt es an der Proxy-Konfiguration; braucht er schon hier ewig, ist die App selbst der Flaschenhals:
504 ist fast immer die Folge einer zu langsamen Anwendung, nicht von nginx. Typische Verdächtige: eine Datenbankabfrage ohne Index, ein externer API-Aufruf, der selbst hängt, oder ein Prozess ohne freie Worker. Erst diese Wurzel beheben, statt nur länger zu warten.
4.
Timeouts nur bei echtem Bedarf erhöhen
Gibt es Anfragen, die legitim lange dauern (Reports, Uploads, Exporte), im server- oder location-Block großzügigere Werte setzen. Bei FastCGI-Upstreams wie PHP-FPM heißt die passende Direktive fastcgi_read_timeout, nicht proxy_read_timeout:
Erst die Syntax prüfen, dann neu laden – ein kaputtes Reload legt sonst die ganze Seite lahm. reload übernimmt die neuen Werte, ohne bestehende Verbindungen abzuwürgen:
nginx -t
systemctl reload nginx
Häufige Fragen (FAQ)
?Was ist der Unterschied zwischen 502 und 504?
Bei 502 Bad Gateway hat der Upstream gar nicht oder mit Unsinn geantwortet – Dienst tot, falscher Port, Verbindung abgelehnt. Bei 504 Gateway Timeout war der Upstream durchaus erreichbar, hat aber nicht innerhalb der eingestellten Zeit geantwortet. 502 heißt „macht nicht auf“, 504 heißt „lässt mich vor der Tür warten, bis ich gehe“.
Es kaschiert das Symptom, löst aber selten die Ursache. Braucht eine Anfrage 60 Sekunden, stimmt meist etwas an der App nicht – eine lahme Datenbankabfrage, ein hängender externer Dienst, fehlende Indizes. Ein höherer Timeout gibt der App nur mehr Zeit, langsam zu bleiben. Erst die Ursache finden, dann bei echtem Bedarf den Timeout maßvoll anheben.
Belege
Diese Seite ist gegen die folgenden Primärquellen geprüft – Hersteller, Standard oder Gesetzestext. Wer es nicht glaubt, muss es nicht: Da steht, wo es nachzulesen ist.
nginx liefert 502 Bad Gateway? Der Upstream antwortet nicht wie erwartet. So findest du Dienst-, Timeout- und Berechtigungsursachen und reparierst sie.