nginx liefert 502 Bad Gateway? Der Upstream antwortet nicht wie erwartet. So findest du Dienst-, Timeout- und Berechtigungsursachen und reparierst sie.
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 nicht, im Browser steht nur nüchtern 502 Bad Gateway und
darunter oft der Servername. Statische Dateien funktionieren vielleicht noch,
aber alles Dynamische – Login, API, das ganze CMS – quittiert mit derselben
kurzen Fehlerseite. nginx läuft, die Seite trotzdem nicht.
Die „Layer 8“-Wahrheit
502 ist nicht nginx’ eigener Fehler, sondern seine ehrliche Meldung über jemand
anderen. nginx steht als Türsteher vor dem eigentlichen Dienst und reicht
Anfragen an diesen Upstream weiter – PHP-FPM, eine Node-App, ein Gunicorn.
Sagt der Türsteher 502, dann hat der Laden dahinter nicht aufgemacht oder mitten
im Satz aufgelegt. Deshalb ist der Reflex, nginx neu zu starten, meist
wirkungslos: Der Fehler sitzt eine Etage tiefer. Wer ins Errorlog schaut, bekommt
die Ursache fast wörtlich serviert – toter Dienst, falscher Port, zu kurzer
Timeout oder eine SELinux-Regel, die die Verbindung gar nicht erst zulässt.
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. Sie unterscheidet 'Dienst nicht erreichbar' von 'Dienst bricht ab' und spart alles Raten:
tail -n 50 /var/log/nginx/error.log
2.
Den Upstream-Dienst prüfen und starten
In den meisten Fällen ist schlicht der dahinterliegende Dienst gestorben. Status prüfen und bei Bedarf neu starten (Dienstname je nach Setup, z. B. php-fpm, gunicorn, node):
systemctl status php-fpm
systemctl restart php-fpm
3.
nginx-Konfiguration validieren
Ein falscher proxy_pass, ein vertippter Port oder ein nicht existierender Socket führt direkt zu 502. Erst testen, dann neu laden – ein kaputtes Reload legt sonst alles lahm:
nginx -t
systemctl reload nginx
4.
Den Upstream direkt ansprechen
nginx umgehen und den Dienst direkt anfragen. Antwortet er hier, liegt es an der Proxy-Konfiguration; antwortet er nicht, am Dienst selbst (Port an dein Setup anpassen). Achtung: Das gilt nur für Dienste, die HTTP sprechen — etwa Gunicorn oder Node. PHP-FPM auf Port 9000 spricht FastCGI, kein HTTP; dort liefert curl auch dann keine Antwort, wenn der Dienst kerngesund ist. Für FastCGI braucht es cgi-fcgi:
Auf RHEL, Fedora und AlmaLinux verbietet SELinux nginx standardmäßig ausgehende Netzverbindungen zum Upstream – typisch bei Reverse-Proxys. Gezielt erlauben:
setsebool -P httpd_can_network_connect 1
Häufige Fragen (FAQ)
?Was bedeutet 502 Bad Gateway bei nginx?
nginx arbeitet als Vermittler (Reverse Proxy) und hat die Anfrage an einen dahinterliegenden Dienst – den Upstream, etwa PHP-FPM oder eine App – weitergereicht. 502 heißt: Dieser Upstream hat gar nicht oder mit einer ungültigen Antwort reagiert. Der Fehler liegt fast immer hinter nginx, nicht in nginx selbst.
?Wo finde ich die genaue Ursache?
Im nginx-Errorlog, üblicherweise unter /var/log/nginx/error.log. Formulierungen wie 'connect() failed', 'Connection refused' oder 'upstream prematurely closed connection' sagen präzise, ob der Upstream tot ist, abgelehnt hat oder mitten in der Antwort abgebrochen ist.
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 504 Gateway Timeout? Der Upstream antwortet nicht rechtzeitig, bevor nginx aufgibt. So findest du die Ursache und setzt Timeouts sinnvoll.
SELinux verweigert einem Dienst den Zugriff (AVC denial)? Statt dauerhaft setenforce 0 lieber das Audit-Log lesen und Kontext oder Boolean korrigieren.
Nach dem Verschieben von Dateien meldet ein Dienst 'Permission denied', obwohl die Rechte stimmen? Der SELinux-Kontext fehlt, restorecon repariert ihn.