Ein 502-Bad-Gateway-Fehler in Nginx bedeutet in der Regel, dass Nginx keine gültige Antwort von einem Upstream-Server wie PHP-FPM, Node.js oder einer anderen Backend-Anwendung erhalten hat.
Die häufigsten Ursachen sind gestoppte Anwendungsdienste, falsch konfigurierte Upstream-Ports oder -Sockets sowie Backend-Prozesse, die abstürzen oder Verbindungen unerwartet schließen.
Prüfen Sie zuerst die Fehlerprotokolle von Nginx. Daraus geht oft genau hervor, warum die Verbindung fehlgeschlagen ist.
Diese Anleitung führt Sie durch sieben praktische Schritte zur Fehlersuche auf Linux-Servern mit Nginx.
Was verursacht einen 502-Bad-Gateway-Fehler in Nginx?
Nginx fungiert häufig als Reverse-Proxy, der Anfragen an Backend-Anwendungen weiterleitet und deren Antworten an Besucher zurückgibt.
Wenn der Upstream-Dienst nicht korrekt antwortet, kann Nginx den HTTP-Statuscode 502 zurückgeben.
Häufige Ursachen sind:
- Backend-Dienste, die gestoppt wurden oder abgestürzt sind.
- Falsche Upstream-IP-Adressen, -Ports oder -Unix-Sockets.
- Ausfälle von PHP-FPM oder Anwendungsprozessen.
- Berechtigungsprobleme beim Zugriff auf Sockets.
- Zu wenig Arbeitsspeicher oder Speicherplatz.
- Ungültige oder vorzeitig geschlossene Upstream-Verbindungen.
Für die folgenden Prüfungen benötigen Sie SSH-Zugriff und die Berechtigung, Ihren Linux-Server zu verwalten.
1. Prüfen Sie die Nginx-Fehlerprotokolle
Die Nginx-Fehlerprotokolle sind meist der schnellste Weg, die Ursache eines 502-Fehlers zu finden.
Verbinden Sie sich per SSH mit Ihrem Server und führen Sie Folgendes aus:
sudo tail -n 50 /var/log/nginx/error.logDamit werden die letzten 50 Protokolleinträge angezeigt.
Verwenden Sie für die Fehlersuche in Echtzeit:
sudo tail -f /var/log/nginx/error.logLaden Sie die betroffene Webseite neu und achten Sie auf neue Meldungen.
| Protokollmeldung | Wahrscheinliche Ursache |
|---|---|
connect() failed (111: Connection refused) | Das Backend nimmt keine Verbindungen an |
No such file or directory | Der konfigurierte Upstream-Socket fehlt |
Permission denied | Nginx kann nicht auf den Socket oder die Ressource zugreifen |
upstream prematurely closed connection | Das Backend hat die Verbindung unerwartet geschlossen |
upstream sent invalid header | Das Backend hat fehlerhafte Antwort-Header zurückgegeben |
Je nach Hosting-Konfiguration können sich die Protokolle an einem anderen Ort befinden.
Ändern Sie keine Nginx-Einstellungen, bevor Sie die wahrscheinliche Ursache ermittelt haben.
2. Prüfen Sie, ob der Backend-Dienst läuft
Ein 502-Fehler tritt häufig auf, weil die Anwendung hinter Nginx nicht mehr läuft.
Führen Sie für einen von systemd verwalteten Anwendungsdienst Folgendes aus:
sudo systemctl status myappErsetzen Sie myapp durch den tatsächlichen Namen Ihres Dienstes.
Bei PHP-Anwendungen mit PHP-FPM könnte der Dienst beispielsweise so heißen:
sudo systemctl status php8.3-fpmDie installierte PHP-Version und der Dienstname können abweichen.
Wenn der Dienst ausgefallen ist, prüfen Sie seine Protokolle:
sudo journalctl -u myapp -n 50Suchen Sie nach Abstürzen, fehlenden Abhängigkeiten, Konfigurationsfehlern oder speicherbedingten Ausfällen.
Starten Sie den Dienst erst neu, nachdem Sie das zugrunde liegende Problem erkannt und behoben haben.
3. Überprüfen Sie den Upstream-Port oder -Socket
Nginx muss Anfragen an die richtige Backend-Adresse weiterleiten.
Ein Reverse-Proxy könnte beispielsweise Folgendes enthalten:
location / {
proxy_pass http://127.0.0.1:3000;
}Damit wird Nginx angewiesen, Anfragen an eine HTTP-Anwendung weiterzuleiten, die auf Port 3000 lauscht.
Prüfen Sie, ob dort ein Dienst lauscht:
sudo ss -ltnp | grep ':3000'Sie können ein HTTP-Backend auch direkt testen:
curl -i http://127.0.0.1:3000/Wenn das Backend nicht erreichbar ist, untersuchen Sie dessen Dienstkonfiguration, bevor Sie Nginx ändern.
Prüfen Sie die PHP-FPM-Sockets
PHP-FPM verwendet häufig Unix-Sockets oder TCP-Ports.
Eine Nginx-Konfiguration könnte Folgendes enthalten:
fastcgi_pass unix:/run/php/php8.3-fpm.sock;Prüfen Sie, ob der konfigurierte Socket existiert:
ls -l /run/php/Der Socket-Pfad muss mit der Einstellung listen des PHP-FPM-Pools übereinstimmen, und Nginx muss die Berechtigung haben, eine Verbindung herzustellen.
Wichtig: proxy_pass wird für HTTP-Upstream-Dienste verwendet, fastcgi_pass dagegen für FastCGI-Dienste wie PHP-FPM. Sie sind nicht austauschbar.
4. Prüfen Sie Arbeitsspeicher und Speicherplatz des Servers
Backend-Anwendungen können abstürzen oder nicht mehr reagieren, wenn dem Server die Ressourcen ausgehen.
Prüfen Sie den Arbeitsspeicher:
free -hPrüfen Sie den Speicherplatz:
df -hPrüfen Sie die laufenden Prozesse:
topWenn eine Anwendung wegen Speichermangels beendet wurde, finden Sie möglicherweise entsprechende Meldungen im Systemjournal:
sudo journalctl -k --since "1 hour ago"Achten Sie auf Meldungen über Speichermangel oder die Beendigung von Prozessen.
Wenn der Speicherplatz aufgebraucht ist, ermitteln Sie vor dem Löschen von Dateien, was ihn belegt.
5. Prüfen Sie Socket-Berechtigungen und Anwendungsprotokolle
Manchmal läuft das Backend, aber Nginx kann nicht mit ihm kommunizieren.
Prüfen Sie bei Unix-Sockets Eigentümer und Berechtigungen:
ls -l /run/php/Prüfen Sie auch die Verzeichnisse entlang des Pfads zum Socket, wenn die Protokolle einen Berechtigungsfehler melden.
Welche Berechtigungen erforderlich sind, hängt vom Benutzer der Nginx-Worker-Prozesse und der Konfiguration des Backend-Dienstes ab.
Vermeiden Sie weitreichende Berechtigungen wie chmod 777. Passen Sie stattdessen die entsprechende Dienst- oder Pool-Konfiguration so an, dass berechtigte Prozesse auf den Socket zugreifen können.
Wenn die Fehlerprotokolle melden, dass der Upstream seine Verbindung vorzeitig geschlossen hat, suchen Sie in den Protokollen der Backend-Anwendung nach Abstürzen, Ausnahmen oder fehlgeschlagenen Anfragen.
6. Testen Sie Ihre Nginx-Konfiguration
Falsche Proxy-Einstellungen oder Konfigurationsänderungen können die Kommunikation mit dem Upstream ebenfalls stören.
Validieren Sie die Nginx-Konfiguration, bevor Sie Änderungen übernehmen:
sudo nginx -tWenn der Test erfolgreich ist, laden Sie die Nginx-Konfiguration neu:
sudo systemctl reload nginxDurch das Neuladen werden gültige Konfigurationsänderungen übernommen, ohne den Dienst unnötig neu zu starten.
Wenn der Test fehlschlägt, beheben Sie zuerst den gemeldeten Konfigurationsfehler.
Erhöhen Sie Proxy-Timeouts oder Pufferlimits nicht auf Verdacht. Dadurch lassen sich weder ein gestopptes Backend noch ein falscher Socket oder eine abgelehnte Verbindung beheben.
7. Vergewissern Sie sich, dass der 502-Fehler behoben ist
Testen Sie nach der Behebung des zugrunde liegenden Problems die betroffene URL:
curl -I https://example.comErsetzen Sie example.com durch Ihre tatsächliche Domain.
Eine erfolgreiche Anfrage liefert normalerweise einen passenden HTTP-Status wie 200 OK, wobei Weiterleitungen und andere gültige Antworten andere Statuscodes zurückgeben können.
Öffnen Sie die Website außerdem in Ihrem Browser und prüfen Sie die Nginx-Fehlerprotokolle erneut.
Wenn der Fehler unter Last erneut auftritt, überwachen Sie den Backend-Dienst und die Ressourcennutzung, während Sie das Problem reproduzieren.
So beugen Sie 502-Fehlern in Nginx vor
Nicht jeder Backend-Ausfall lässt sich verhindern, aber eine gute Serververwaltung reduziert vermeidbare Ausfallzeiten.
- Überwachen Sie den Zustand von Nginx und den Backend-Diensten.
- Prüfen Sie nach Deployments die Anwendungsprotokolle.
- Konfigurieren Sie geeignete Richtlinien zur Wiederherstellung von Diensten.
- Überwachen Sie die Nutzung von Arbeitsspeicher, Speicherplatz und Verbindungen.
- Validieren Sie Konfigurationsänderungen, bevor Sie sie übernehmen.
- Testen Sie Anwendungen direkt, bevor Sie den Datenverkehr über Nginx leiten.
Wenn eine Anwendung mehr Ressourcen benötigt, messen Sie ihren tatsächlichen Verbrauch, bevor Sie die Serverkapazität erhöhen.
Häufig gestellte Fragen
Der Fehler bedeutet, dass Nginx als Gateway oder Proxy eine ungültige Antwort von einem Upstream-Server erhalten hat. Die Ursache ist häufig ein gestoppter Backend-Dienst oder ein Problem mit der Upstream-Verbindung.
Nicht unbedingt. Ein Neustart oder Neuladen von Nginx behebt weder eine nicht erreichbare Anwendung noch einen falschen Backend-Port oder einen fehlenden PHP-FPM-Socket.
Ein 502-Fehler weist auf eine ungültige Antwort des Upstream-Servers hin. Ein 504-Fehler bedeutet dagegen, dass das Gateway innerhalb der Zeitüberschreitungsfrist keine Antwort vom Upstream-Server erhalten hat.
Ja. Wenn der Arbeitsspeicher erschöpft ist, können Backend-Prozesse abstürzen oder beendet werden, sodass Nginx nicht mehr mit ihnen kommunizieren kann.
Nein. Auch andere Gateways, Proxys, CDNs und Load Balancer können HTTP-502-Fehler zurückgeben.
Fazit
Um einen 502-Bad-Gateway-Fehler in Nginx zu beheben, müssen Sie zunächst herausfinden, warum die Upstream-Anwendung nicht korrekt antwortet.
Prüfen Sie zuerst die Nginx-Fehlerprotokolle, vergewissern Sie sich, dass der Backend-Dienst läuft, und überprüfen Sie den konfigurierten Port oder Socket. Untersuchen Sie anschließend Ressourcenengpässe, Berechtigungen und Anwendungsfehler.
In den meisten Fällen ist es wirksamer, den konkreten Upstream-Fehler zu ermitteln, als Nginx wiederholt neu zu starten oder Timeout-Einstellungen zu ändern.
