Zum Inhalt springen
SONOYA.com
Selfhosting & Web

nginx 502 Bad Gateway und 504 Timeout beheben

nginx meldet 502 Bad Gateway oder 504 Gateway Timeout? So liest Du das error.log, testest das Backend direkt und behebst Port, Socket und Timeout.

Von

Getrennter Stecker mit rotem Kreuz auf dunkelgrünem Grund, Sinnbild für nginx, das sein Backend nicht erreicht und 502 Bad Gateway meldet

Du rufst Deine Website oder Deinen selbst gehosteten Dienst auf, und statt der Seite zeigt nginx nur „502 Bad Gateway“ oder „504 Gateway Timeout“. Beide Meldungen sagen dasselbe Grundsätzliche: nginx selbst läuft, aber das Programm dahinter, an das nginx die Anfrage weiterreicht, antwortet nicht oder nicht rechtzeitig. Hier zeige ich Dir, wie Du in wenigen Minuten herausfindest, welches der typischen Probleme es ist, und wie Du es behebst, egal ob hinter nginx eine Node- oder Python-App, PHP-FPM oder ein Docker-Container steckt.

Die Befehle gelten für nginx auf Ubuntu 26.04 LTS und Debian 13, auf anderen Distributionen weichen höchstens die Pfade ab.

502 oder 504: was der Unterschied verrät

nginx arbeitet in diesen Fällen als Reverse Proxy. Es nimmt die Anfrage aus dem Internet an und reicht sie per proxy_pass oder fastcgi_pass an ein Backend weiter, das die Doku „upstream“ nennt. Die beiden Fehlercodes zeigen, an welcher Stelle es hakt:

  • 502 Bad Gateway heißt, nginx hat vom Backend keine brauchbare Antwort bekommen. Meist erreicht es das Backend gar nicht, weil es nicht läuft, auf einem anderen Port lauscht oder der Socket fehlt. Seltener bricht das Backend die Verbindung mitten in der Antwort ab.
  • 504 Gateway Timeout heißt, nginx hat das Backend erreicht, aber innerhalb der Wartezeit kam keine Antwort. Das Backend läuft also, ist aber zu langsam oder hängt.

Diese Unterscheidung spart Dir schon die halbe Fehlersuche. Bei 502 suchst Du nach einem Verbindungsproblem, bei 504 nach etwas, das zu lange dauert.

Schritt 1: Das error.log lesen

Der Browser zeigt nur den Statuscode, den genauen Grund schreibt nginx in sein Fehlerprotokoll. Ruf die Seite noch einmal auf und sieh Dir direkt danach die letzten Zeilen an:

Code
sudo tail -n 30 /var/log/nginx/error.log

Hat Dein server-Block ein eigenes error_log, etwa /var/log/nginx/meinedomain.error.log, schau dort nach. Welche Datei gilt, findest Du mit sudo grep -r error_log /etc/nginx/. Läuft nginx selbst in Docker, landen die Meldungen nicht in einer Datei, sondern in den Container-Logs, die Du mit docker compose logs --tail 30 nginx liest (ersetze nginx durch den Namen des Dienstes in Deiner compose.yaml).

Eine typische Zeile sieht so aus:

Code
2026/11/21 10:42:17 [error] 1234#1234: *56 connect() failed (111: Connection refused) while connecting to upstream, client: 203.0.113.7, server: app.example.com, request: "GET / HTTP/2.0", upstream: "http://127.0.0.1:3000/", host: "app.example.com"

Wichtig sind zwei Teile: die Meldung in der Mitte und die Angabe hinter upstream:. Letztere zeigt, welche Adresse nginx tatsächlich angesprochen hat. Schon hier fallen viele Fehler auf, etwa ein falscher Port oder 127.0.0.1, wo ein Containername stehen müsste.

Schritt 2: Die Meldung zuordnen

Die folgenden Meldungen decken den Großteil aller Fälle ab. Such Dir die passende heraus und spring zum jeweiligen Abschnitt.

Meldung im error.logCodeUrsache
connect() failed (111: Connection refused)502Unter dieser Adresse lauscht nichts
connect() to unix:/run/php/... failed (2: No such file or directory)502PHP-FPM-Socket existiert nicht
connect() to unix:/run/php/... failed (13: Permission denied)502nginx darf den Socket nicht öffnen
upstream prematurely closed connection502Backend bricht ab oder stürzt ab
upstream sent too big header502Antwort-Header größer als der Puffer
no live upstreams502Alle Server im upstream-Block gelten als ausgefallen
upstream timed out (110: Connection timed out)504Backend antwortet zu langsam

Connection refused: Das Backend läuft nicht oder lauscht woanders

Das ist der häufigste Fall. Prüf zuerst, ob das Backend überhaupt läuft und auf welchem Port es lauscht:

Code
sudo ss -tlnp

Die Ausgabe listet alle Programme, die auf TCP-Verbindungen warten. In der Spalte Local Address:Port suchst Du den Port aus Deinem proxy_pass, ganz rechts steht der Prozess. Fehlt der Port, läuft das Backend nicht. Bei einem systemd-Dienst zeigt sudo systemctl status meinedienst den Zustand, und sudo journalctl -u meinedienst -n 50 verrät, warum er nicht startet. Wie Du diese Protokolle gezielt durchsuchst, erklärt der Artikel journalctl: Fehler unter Linux in den Logs finden.

Steht der Port in der Liste, teste das Backend direkt, also an nginx vorbei:

Code
curl -I http://127.0.0.1:3000

Ersetze 3000 durch den Port aus Deinem proxy_pass. Kommt hier eine Antwort mit HTTP/1.1 200 OK oder einem Redirect, funktioniert das Backend, und der Fehler liegt in der nginx-Konfiguration, meist in einem Tippfehler bei Port oder Adresse. Kommt Connection refused, liegt das Problem beim Backend selbst.

Achte in der ss-Ausgabe auch auf die Adresse vor dem Port. 127.0.0.1:3000 ist nur lokal erreichbar, 0.0.0.0:3000 oder *:3000 auf allen Schnittstellen. Zeigt Dein proxy_pass auf eine andere IP als die, auf der das Backend lauscht, kommt die Verbindung nicht zustande.

Docker: 127.0.0.1 zeigt auf den falschen Rechner

Bei Containern ist 127.0.0.1 die häufigste Falle, denn die Adresse bedeutet immer „ich selbst“. Je nach Aufbau gilt Folgendes:

  • nginx läuft direkt auf dem Server, die App im Container. Dann muss der Container seinen Port auf dem Host veröffentlichen, in der compose.yaml etwa mit ports: - "127.0.0.1:3000:3000". Danach funktioniert proxy_pass http://127.0.0.1:3000;. Prüf mit docker compose ps, ob in der Spalte PORTS die Weiterleitung auftaucht.
  • nginx läuft selbst im Container. Dann ist 127.0.0.1 der nginx-Container, nicht Deine App. Beide Container müssen im selben Docker-Netzwerk hängen, und im proxy_pass steht der Dienstname aus der compose.yaml, zum Beispiel proxy_pass http://app:3000;. Gemeint ist der Port im Container, nicht ein veröffentlichter Port auf dem Host.
  • Die App im Container lauscht nur auf 127.0.0.1. Manche Entwicklungsserver binden sich standardmäßig nur an localhost. Dann ist die App von außerhalb ihres eigenen Containers nicht erreichbar, egal wie die Ports gesetzt sind. Stell die App so ein, dass sie auf 0.0.0.0 lauscht, bei vielen Frameworks über eine Option wie --host 0.0.0.0.

Eine Besonderheit tritt auf, wenn nginx im Container läuft und Du den App-Container neu erstellst: nginx löst den Dienstnamen beim Start einmal auf und merkt sich die IP. Bekommt der neue App-Container eine andere Adresse, meldet nginx 502, obwohl alles läuft. Ein docker compose restart nginx behebt das. Startet der App-Container gar nicht erst, hilft Dir der Artikel Docker-Container startet nicht: Logs und Exit-Codes weiter.

PHP-FPM: Socket fehlt oder Rechte stimmen nicht

Bei WordPress und anderen PHP-Seiten spricht nginx über fastcgi_pass meist einen Unix-Socket an. Meldet das Log No such file or directory, passt der Pfad in der nginx-Konfiguration nicht zum tatsächlichen Socket, typischerweise nach einem PHP-Update, das die Versionsnummer im Namen ändert. Sieh nach, welche Sockets es gibt:

Code
ls -l /run/php/

Dort steht zum Beispiel php8.4-fpm.sock. Trag genau diesen Namen in Deiner Seitenkonfiguration unter /etc/nginx/sites-available/ bei fastcgi_pass unix:/run/php/php8.4-fpm.sock; ein. Ist das Verzeichnis leer, läuft PHP-FPM nicht. Starte es mit sudo systemctl start php8.4-fpm und ersetze 8.4 durch Deine Version, die Dir php -v anzeigt.

Meldet das Log Permission denied, darf der nginx-Benutzer den Socket nicht öffnen. Der Socket gehört dem Benutzer, der in der Pool-Datei /etc/php/8.4/fpm/pool.d/www.conf bei listen.owner und listen.group steht. Auf Ubuntu und Debian ist das www-data, und nginx läuft ebenfalls als www-data. Hast Du einen der beiden Werte geändert, stell sie wieder auf denselben Benutzer und starte PHP-FPM mit sudo systemctl restart php8.4-fpm neu.

Upstream prematurely closed: Das Backend bricht ab

Hier hat nginx eine Verbindung bekommen, aber das Backend hat sie geschlossen, bevor eine vollständige Antwort kam. Fast immer ist das Backend dabei abgestürzt, etwa wegen eines Programmfehlers oder weil der Arbeitsspeicher ausging. Die Ursache steht deshalb nicht im nginx-Log, sondern im Log der App, also in journalctl -u meinedienst oder docker compose logs app. Such dort nach einem Stacktrace oder nach Killed, was auf den OOM-Killer des Kernels hinweist.

Too big header: Puffer vergrößern

Schickt das Backend sehr große Header, etwa viele Cookies oder lange Tokens bei einer Anmeldung, reicht der Standardpuffer nicht. Vergrößere ihn im passenden location-Block:

Code
proxy_buffer_size 16k;
proxy_buffers 8 16k;

Bei PHP heißen die Gegenstücke fastcgi_buffer_size und fastcgi_buffers.

No live upstreams: Alle Server sind gesperrt

Nutzt Du einen upstream-Block mit mehreren Servern, markiert nginx einen Server nach einem Fehlversuch für zehn Sekunden als nicht verfügbar (die Standardwerte max_fails=1 und fail_timeout=10s). Sind alle gesperrt, erscheint diese Meldung. Sie ist eine Folge, keine Ursache. Scroll im Log nach oben zur ersten Meldung davor, dort steht meist ein Connection refused oder ein Timeout, und behebe das.

Upstream timed out: Mehr Zeit geben

Bei 504 antwortet das Backend langsamer, als nginx wartet. proxy_read_timeout steht standardmäßig auf 60 Sekunden und misst die Zeit zwischen zwei Lesevorgängen, nicht die Gesamtdauer der Antwort. Für einen langen Export, einen Upload oder eine KI-Anfrage reicht das oft nicht. Erhöhe den Wert gezielt nur für die betroffene Adresse:

Code
location /export/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_read_timeout 300s;
}

Bei PHP-FPM heißt die Einstellung fastcgi_read_timeout. Denk daran, dass auch das Backend eigene Grenzen hat, bei PHP etwa max_execution_time und request_terminate_timeout im Pool. Ein längerer Timeout bei nginx nützt nichts, wenn PHP das Skript vorher beendet. Kommt der 504 schon bei einfachen Seitenaufrufen, ist ein höherer Timeout die falsche Lösung. Dann ist das Backend überlastet oder wartet selbst auf etwas, meist auf eine Datenbank, und genau das musst Du in dessen Logs suchen.

Schritt 3: Änderung prüfen und übernehmen

Nach jeder Änderung an der nginx-Konfiguration prüfst Du zuerst die Syntax:

Code
sudo nginx -t

Erscheinen die Zeilen syntax is ok und test is successful, lädst Du die Konfiguration neu, ohne laufende Verbindungen zu unterbrechen:

Code
sudo systemctl reload nginx

Meldet nginx -t einen Fehler, nennt es Datei und Zeilennummer. Bei einem fehlerhaften Test lädt reload die neue Konfiguration ohnehin nicht, nginx läuft dann mit der alten weiter. Läuft nginx im Container, testest Du mit docker compose exec nginx nginx -t und lädst mit docker compose exec nginx nginx -s reload neu.

Woran Du erkennst, dass es behoben ist

Ruf die Seite erneut auf und prüf sie zusätzlich auf der Kommandozeile:

Code
curl -I https://app.example.com

Ersetze app.example.com durch Deine Domain. Die erste Zeile sollte jetzt HTTP/2 200 oder einen Redirect wie 301 zeigen statt 502 oder 504. Ein weiteres sudo tail -n 5 /var/log/nginx/error.log sollte keine neuen Einträge mit upstream mehr enthalten.

Hast Du bei der Fehlersuche gemerkt, dass Dein Zertifikat abläuft oder HTTPS noch fehlt, hilft Dir die Anleitung Let’s Encrypt mit certbot: HTTPS für nginx einrichten weiter. Die meisten 502-Fehler sind am Ende keine Rätsel, sondern ein Backend, das nicht läuft, oder eine Adresse, die nicht passt. Mit dem error.log und einem direkten curl auf das Backend findest Du beides in wenigen Minuten. Die vollständige Beschreibung aller Proxy-Einstellungen steht in der offiziellen Doku zum Modul ngx_http_proxy_module, die Optionen für upstream-Blöcke in der Doku zu ngx_http_upstream_module.

Weiterlesen.