502, 504 und andere Nginx-Fehler: Ursachen und Lösungen

• Server und Infrastruktur
• Aktualisiert: 04.10.2026
• Ca. 12 Min. Lesezeit

Wo entsteht der Fehler und wie wird er diagnostiziert?

1. 1

   Bestimmen, wo der Fehler entsteht

   Eine Anfrage durchläuft drei Stationen: den Client (Browser), Nginx und das Backend (den Prozess, der die Anwendung ausführt, etwa PHP-FPM, Node.js oder Python). Jeder Code weist auf eine dieser Stationen:

   • Entscheidung von Nginx selbst: 403, 404 (bei statischen Dateien), 413. Die Anfrage hat das Backend möglicherweise nie erreicht.
   • Zwischen Nginx und dem Backend: 502 und 504. Nginx läuft, bekommt von der Anwendung dahinter aber keine ordentliche Antwort.
   • In der Anwendung: 500 sowie ein von der Anwendung zurückgegebenes 404 oder 403. Nginx reicht diese Antwort unverändert weiter.
   • Auf der Client-Seite: 499. Der Client hat die Verbindung geschlossen, ohne die Antwort abzuwarten.

   : Vergrößern

2. 2

   Die Logs lesen

   Nginx führt zwei Logs. Das Zugriffslog (access.log) hält jede Anfrage mit ihrem Statuscode fest: welche Adresse, wann, mit welchem Code beendet? Das Fehlerlog (error.log) nennt die Ursache des Problems. In den meisten Installationen liegen beide unter /var/log/nginx/; Hosting-Verwaltungsoberflächen können die Logs einzelner Websites in einem anderen Ordner ablegen. Der genaue Pfad steht in den Direktiven access_log und error_log der Konfiguration.

   Bash

   # Die letzten 50 Zeilen des Fehlerlogs (Pfad in den meisten Installationen)
   sudo tail -n 50 /var/log/nginx/error.log
   
   # Das Log live verfolgen; den Fehler währenddessen im Browser auslösen
   sudo tail -f /var/log/nginx/error.log
   
   # Die letzten Zeilen des Zugriffslogs: Anfrage, Statuscode, Größe
   sudo tail -n 50 /var/log/nginx/access.log

   Eine Zeile im Fehlerlog enthält in der Regel das Problem selbst (z. B. connect() failed), die Adresse der Anfrage und die mit upstream: beginnende Backend-Adresse. Diese Zeile sagt Ihnen, welche Ursache Sie in den folgenden Abschnitten nachschlagen sollten.

3. 3

   502 und 504 unterscheiden

   Beide sagen „es gibt ein Problem mit dem Backend“, beschreiben aber Verschiedenes. 502 bedeutet, dass Nginx sich nicht mit dem Backend verbinden konnte oder die Verbindung abbrach, bevor eine Antwort kam; der Fehler erscheint meist sofort. 504 bedeutet, dass die Verbindung zustande kam, die Antwort aber nicht innerhalb der Zeitüberschreitung (Timeout) eintraf; der Fehler erscheint nach Ablauf der Wartezeit (standardmäßig 60 Sekunden).

   : Vergrößern

4. 4

   Der Reihe nach diagnostizieren

   1. Code, Adresse und Uhrzeit notieren. Tritt der Fehler bei jeder Anfrage auf, nur auf einer bestimmten Seite oder nur zu Stoßzeiten?
   2. Im Fehlerlog zu dieser Uhrzeit nachsehen. Gibt es keine Zeile, stammt der Code höchstwahrscheinlich aus der Anwendung.
   3. Läuft das Backend? Prüfen Sie den Status des Dienstes.
   4. Das Backend an Nginx vorbei aufrufen. Senden Sie vom Server aus eine Anfrage direkt an die Adresse der Anwendung: Kommt eine Antwort, und wie lange dauert sie?
   5. Die Konfiguration durchsehen. Stimmen Adresse und Port, passen Grenzen und Timeouts, reichen die Dateirechte aus?
   6. Beheben, testen, neu laden.

   Bash

   # Läuft Nginx?
   sudo systemctl status nginx
   
   # Läuft der Backend-Dienst? (Dienstnamen an Ihr System anpassen)
   sudo systemctl status php-fpm
   
   # Das Backend an Nginx vorbei aufrufen (für Anwendungen, die per HTTP lauschen)
   curl -I http://127.0.0.1:3000/
   
   # Dieselbe Adresse über Nginx aufrufen
   curl -I http://beispiel.de/

   Der Dienstname hängt vom System ab; der Name des PHP-FPM-Dienstes enthält häufig eine Versionsnummer. Die Backend-Adresse entnehmen Sie der proxy_pass-Zeile Ihrer eigenen Konfiguration.

   : Vergrößern

5. 5

   Den Code erkennen und zum passenden Abschnitt gehen

   Die folgende Tabelle fasst die häufigsten Codes zusammen; die Einzelheiten stehen in den Abschnitten darunter.

   Code	Bedeutung	Häufigste Ursache	Zuerst nachsehen
   502	Bad Gateway: keine gültige Antwort vom Backend	Anwendung läuft nicht, falsche Adresse oder falscher Socket	error.log, Dienststatus
   504	Gateway Timeout: Das Backend hat nicht rechtzeitig geantwortet	Langsame Abfrage oder Aufgabe, kurzes Timeout	error.log, Anwendungslog
   413	Request Entity Too Large: Der Anfrage-Body ist zu groß	Die Grenze client_max_body_size	Konfiguration
   499	Der Client hat die Verbindung geschlossen (Nginx-spezifisch)	Langsame Antwort, ungeduldiger Client oder Timeout der vorgelagerten Schicht	access.log
   403	Forbidden: kein Zugriff erlaubt	Dateirechte, keine Indexdatei, deny-Regel	error.log
   404	Not Found: Adresse nicht gefunden	Falsches root, fehlende Datei, nicht passende location	error.log, Anwendung
   500	Internal Server Error: interner Serverfehler	Anwendungsfehler, Weiterleitungsschleife	Anwendungslog
   503	Service Unavailable: vorübergehend nicht verfügbar	Raten- oder Verbindungsbegrenzung, Wartungsmodus	error.log

   : Vergrößern

502 Bad Gateway

Was bedeutet das? Nginx hat versucht, die Anfrage an das Backend weiterzuleiten, konnte sich aber nicht verbinden oder hat keine gültige Antwort erhalten.

Mögliche Ursachen und ihre Spuren im Log:

• Das Backend läuft nicht oder ist abgestürzt: Im Log steht connect() failed (111: Connection refused).
• Adresse, Port oder Socket-Pfad sind falsch: proxy_pass oder fastcgi_pass zeigt nicht dorthin, wo die Anwendung tatsächlich lauscht. Fehlt die Socket-Datei, steht dort No such file or directory.
• Keine Berechtigung für den Socket: connect() to unix:… failed (13: Permission denied). Der Benutzer, unter dem Nginx läuft, kann nicht auf die Socket-Datei zugreifen. Auf Systemen mit aktiviertem SELinux kann auch die Sicherheitsrichtlinie die Verbindung blockieren.
• Das Backend hat die Verbindung ohne Antwort geschlossen: upstream prematurely closed connection. Der Anwendungsprozess ist während der Anfrage möglicherweise abgestürzt, neu gestartet worden oder an seine Speichergrenze gestoßen.
• Die Antwort-Header passten nicht in den Puffer: upstream sent too big header. Sehr große Cookies oder Header verursachen das; der Wert von proxy_buffer_size wird erhöht.

Lösung: Starten Sie den Dienst und klären Sie anhand des Anwendungslogs, warum er angehalten hat. Gleichen Sie die Adresse mit der ab, auf der die Anwendung lauscht. Einige Sekunden 502 während eines Deployments oder Neustarts sind normal; wiederholt sich der Fehler ständig, stürzt die Anwendung ab. Für PHP-Websites finden Sie Einzelheiten in der Anleitung Nginx und PHP-FPM.

504 Gateway Timeout

Was bedeutet das? Nginx hat sich mit dem Backend verbunden und die Anfrage gesendet, die Antwort kam aber nicht in der erwarteten Zeit. Im Log steht upstream timed out (110: Connection timed out).

Mögliche Ursachen: eine langsame Datenbankabfrage; ein von der Anwendung aufgerufener externer Dienst, der nicht antwortet; ein lang laufender Bericht, Export oder Stapelvorgang; alle Anwendungsprozesse sind wegen hoher Last beschäftigt; läuft das Backend auf einem anderen Server, verwirft eine Firewall die Verbindung stillschweigend.

Diagnose: Sehen Sie nach, welche Adressen in das Timeout laufen: eine einzelne Seite oder die ganze Website? Rufen Sie das Backend direkt auf und messen Sie die Dauer. Die Backend-Zeit im Zugriffslog erleichtert es, langsame Adressen zu finden:

# Auf http-Ebene: Logformat mit Anfragezeit und Backend-Zeit
log_format zeiten '$remote_addr [$time_local] "$request" $status '
                  'anfrage=$request_time backend=$upstream_response_time '
                  'backend_status=$upstream_status';

server {
    listen 80;
    server_name beispiel.de;

    access_log /var/log/nginx/access.log zeiten;

    location / {
        proxy_pass http://127.0.0.1:3000;
    }
}

Lösung: Beseitigen Sie zuerst die Ursache der Langsamkeit (Abfrage, Index, Cache). Verlagern Sie Aufgaben, die naturgemäß lange dauern, in den Hintergrund und antworten Sie dem Benutzer sofort. Ist es wirklich nötig, verlängern Sie die Zeit nur für die betroffene Adresse:

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_connect_timeout 5s;    # nicht lange warten, wenn keine Verbindung zustande kommt
    proxy_read_timeout    60s;   # Standardwert
}

# Längere Wartezeit nur für die lang laufende Berichtsadresse
location /berichte/ {
    proxy_pass http://127.0.0.1:3000;
    proxy_read_timeout 180s;
}

Bei Proxy-Verbindungen bestimmt proxy_read_timeout die Zeit, bei PHP-FPM fastcgi_read_timeout; der Standardwert beider beträgt 60 Sekunden. Ist das Zeitlimit der Anwendung selbst (in PHP etwa max_execution_time) kürzer, prüfen Sie auch dieses. Liegt vor Nginx ein CDN oder eine Schicht für die Lastverteilung (Load Balancing), hat diese ein eigenes Timeout; die Zeit in Nginx zu verlängern wirkt sich darauf nicht aus.

413 Request Entity Too Large

Was bedeutet das? Der vom Client gesendete Anfrage-Body (meist eine hochgeladene Datei) überschreitet die erlaubte Größe. Die Grenze legt client_max_body_size fest; der Standardwert ist 1m, also 1 Megabyte. Im Log steht client intended to send too large body.

# Grenze für den Anfrage-Body der ganzen Website (Standard 1m)
client_max_body_size 2m;

# Höhere Grenze nur für die Upload-Adresse
location /upload/ {
    client_max_body_size 50m;
    proxy_pass http://127.0.0.1:3000;
}

Lösung: Heben Sie die Grenze auf Ihren tatsächlichen Bedarf an; die Direktive kann auf http-, server- oder location-Ebene stehen. Sie nur für die Upload-Adresse anzuheben ist sicherer als für die ganze Website. Gleichen Sie auch die Grenzen der Anwendung an: Sind upload_max_filesize und post_max_size in PHP kleiner, wird der Upload stattdessen von PHP abgelehnt. Zur Prüfung hochgeladener Dateien siehe die Anleitung zur Sicherheit beim Datei-Upload.

499: Der Client hat die Verbindung geschlossen

Was bedeutet das? 499 ist kein Standard-HTTP-Code; er ist Nginx-spezifisch und erscheint nur im Zugriffslog. Der Client hat die Verbindung geschlossen, bevor Nginx die Antwort senden konnte; da niemand mehr da ist, der eine Antwort empfangen könnte, sieht der Besucher diesen Code nie.

Mögliche Ursachen: Der Besucher hat die Seite geschlossen, neu geladen oder eine andere aufgerufen; das eigene Timeout der mobilen App oder des API-Clients ist kürzer als das von Nginx; ein CDN oder Load Balancer vor Nginx hat das Warten aufgegeben.

Diagnose und Lösung: Vereinzelte 499 sind normal. Häufen sie sich bei einer bestimmten Adresse, antwortet diese langsam: Das eigentliche Problem ist die Geschwindigkeit; gehen Sie nach den Schritten im Abschnitt zu 504 vor. Stimmen Sie das Timeout der vorgelagerten Schicht und das Timeout in Nginx aufeinander ab.

403 Forbidden

Was bedeutet das? Der Server hat die Anfrage verstanden, lehnt ihre Ausführung aber ab.

• Dateirechte: Im Log steht (13: Permission denied). Der Benutzer, unter dem Nginx läuft, muss die Datei lesen können und in allen übergeordneten Ordnern das Durchsuchen-Recht (x) besitzen.
• Keine Indexdatei: Im Log steht directory index of … is forbidden. Ein Ordner wurde angefordert, keine der in der Direktive index genannten Dateien wurde gefunden und die Verzeichnisauflistung ist ausgeschaltet. Prüfen Sie den root-Pfad und die index-Zeile.
• Zugriffsregel: Im Log steht access forbidden by rule. Eine deny-Regel hat die Anfrage blockiert; wurde die Regel absichtlich geschrieben (z. B. für versteckte Dateien), ist das das erwartete Verhalten.
• Entscheidung der Anwendung: Steht nichts im Log, kann das 403 von der Anwendung (Berechtigungsprüfung) oder von einer vorgelagerten Sicherheitsschicht stammen.

Lösen Sie ein Rechteproblem nicht, indem Sie „allen volle Rechte“ geben; zu korrekten Besitzverhältnissen und minimalen Rechten siehe die Anleitung Server- und Hosting-Sicherheit.

404 Not Found

Was bedeutet das? Zur angeforderten Adresse wurde nichts gefunden.

• Die Datei existiert wirklich nicht oder root ist falsch: Im Log steht open() "…" failed (2: No such file or directory). Der vollständige Pfad in dieser Zeile zeigt, wo Nginx die Datei gesucht hat; die meisten Konfigurationsfehler werden beim Blick auf diesen Pfad klar.
• Die falsche location hat gepasst: Die Anfrage landet möglicherweise in einem anderen Block, als Sie erwarten.
• Anwendungen mit einem einzigen Einstiegspunkt: In Anwendungen, in denen eine Datei wie index.php alle Adressen bedient, öffnet sich bei fehlender try_files-Zeile die Startseite, während die übrigen Seiten 404 liefern.
• Unpassender Pfad hinter dem Proxy: Gibt die Anwendung das 404 zurück, steht im Nginx-Fehlerlog keine Zeile. Der Schrägstrich am Ende von proxy_pass verändert den Pfad, der an das Backend geht; Einzelheiten stehen in der Anleitung Reverse Proxy einrichten.

500 und 503 in Kürze

500 Internal Server Error kommt meist aus der Anwendung: ein nicht abgefangener Fehler, eine beschädigte Konfigurationsdatei oder ein Problem mit der Datenbankverbindung. Die Ursache steht im Fehlerlog der Anwendung oder von PHP. Nginx selbst erzeugt 500 selten; das typische Beispiel ist eine interne Weiterleitungsschleife, die im Log als rewrite or internal redirection cycle erscheint.

503 Service Unavailable meldet, dass der Dienst vorübergehend nicht erbracht werden kann. Nginx gibt diesen Code standardmäßig zurück, wenn eine Ratenbegrenzung (limit_req) oder Verbindungsbegrenzung (limit_conn) überschritten wird; im Log steht limiting requests oder limiting connections. Auch die im Wartungsmodus absichtlich gesendete Antwort ist 503. Ebenso kann die Anwendung selbst unter hoher Last 503 zurückgeben.

Ein plötzlicher, breiter Anstieg von 502, 503 und 504 kann auch ein Anzeichen für starken Bot-Verkehr sein; siehe DDoS- und Bot-Angriffe.

Nach einer Änderung

Testen Sie jede Änderung an der Konfiguration zuerst und laden Sie dann neu. Schlägt der Test fehl, nennt Nginx Datei und Zeilennummer der fehlerhaften Zeile; solange Sie nicht neu laden, läuft die Website mit den alten Einstellungen weiter.

# Konfiguration testen
sudo nginx -t

# Bei erfolgreichem Test neu laden
sudo systemctl reload nginx

Die dem Besucher gezeigte Fehlerseite sollte weder Version noch Dateipfad noch Fehlerdetails enthalten; die Details bleiben im Log. Beobachten Sie die Logs nach der Behebung einige Tage: Wiederholt sich dieselbe Zeile, besteht die Ursache weiter.

Häufige Fragen

Verwandte Anleitungen

• Nginx als Reverse Proxy einrichtenSchritt für Schritt: server-Block, proxy_pass, weitergereichte Header, WebSocket, Timeouts und echte Client-IP.
• Nginx und PHP-FPM: So laufen PHP-Websites mit Nginxfastcgi_pass, SCRIPT_FILENAME, try_files, das Pool-Konzept, Socket-Berechtigungen und der Fehler 502.
• Was ist Nginx und wofür wird es eingesetzt?Die Rollen von Nginx, die ereignisgesteuerte Architektur, der Unterschied zu Apache, Konfigurationsblöcke und Grundbefehle.
• DDoS- und Bot-AngriffeAnzeichen, CDN und WAF, Ratenbegrenzung, Caching und die Zusammenarbeit mit dem Hosting-Anbieter.