502 Bad Gateway

Was dieser Fehler bedeutet und wie du ihn erkennst

• Der Browser zeigt 502 Bad Gateway oder Bad Gateway, teilweise mit dem Branding von Nginx, Apache, Cloudflare oder einem anderen Proxy.
• Der Fehler betrifft mehrere Benutzer, beginnt nach einem Deployment oder einer Konfigurationsänderung oder tritt bei steigendem Traffic auf.
• Die Fehler können sporadisch auftreten, wenn Backend-Worker, Arbeitsspeicher, CPU oder Datenbankverbindungen erschöpft sind.
• Das Proxy-Protokoll meldet eine fehlgeschlagene Upstream-Verbindung, einen Timeout, eine nicht lesbare Statuszeile, eine fehlerhafte Antwort, zu große Header oder einen Socket-Fehler.
• Eine direkte Anfrage an den Origin funktioniert, während dieselbe Anfrage über ein CDN 502 zurückgibt. Das deutet auf Probleme beim CDN-zu-Origin-Zugriff, mit der Firewall, TLS oder dem Routing hin.

Hauptursachen nach Wahrscheinlichkeit

1. Backend gestoppt oder stürzt ab: PHP-FPM, Node.js, Gunicorn oder ein anderer Anwendungsprozess wurde beendet, befindet sich in einer Crash-Schleife oder konnte nach einem Deployment nicht gestartet werden.
2. Backend überlastet oder Timeout: Worker, Arbeitsspeicher, CPU, Datenbankverbindungen oder eine andere Abhängigkeit sind erschöpft, sodass der Proxy nicht rechtzeitig eine Antwort erhält.
3. Falsche Upstream-Konfiguration: Der Proxy verwendet den falschen Host, Port, die falsche Container-Adresse, den falschen Unix-Socket oder Anwendungspfad.
4. Fehler beim Socket- oder Firewall-Zugriff: Der Proxy kann das Backend wegen Socket-Berechtigungen, einer Netzwerkregel, einer Firewall oder einer Änderung an einer Security Group nicht erreichen.
5. Ungültige oder zu große Backend-Antwort: Die Anwendung sendet eine fehlerhafte Ausgabe, eine nicht verwendbare Statuszeile oder Header, die größer sind, als der Proxy akzeptiert.
6. Fehler bei der Verbindung vom CDN zum Origin: Ein CDN kann den Origin nicht erreichen, wird von der Origin-Firewall blockiert oder kann die von seiner Origin-Konfiguration erwartete HTTPS-Verbindung nicht herstellen.

So behebst du den Fehler

1. Ermitteln, wo der 502-Fehler erzeugt wird

Prüfen Sie, ob die Fehlerseite das Branding von Nginx, Apache, Cloudflare, einer Hosting-Plattform oder eines anderen Vermittlers trägt. Stellen Sie fest, ob alle Routen oder nur ein bestimmter Anwendungspfad fehlschlagen, und notieren Sie den Zeitpunkt des Fehlers sowie die betroffene URL. So können Sie die Anfrage den richtigen Protokollen zuordnen.

2. Backend-Prozess und Protokolle prüfen

Prüfen Sie mit autorisiertem Zugriff auf den Server oder das Hosting-Panel, ob der Anwendungsprozess ausgeführt wird und Anfragen annimmt. Durchsuchen Sie die Protokolle nach Crash-Schleifen, fatalen Anwendungsfehlern, Beendigung wegen Speichermangels, fehlenden Abhängigkeiten oder Startfehlern.

Eine beispielhafte, schreibgeschützte Dienstprüfung kann so aussehen:

systemctl status php8.2-fpm
systemctl status nginx
pm2 status

Verwenden Sie die installierte PHP-FPM-Version und den eingesetzten Process Manager, statt diese Namen unverändert zu übernehmen. Wenn das Backend gestoppt ist oder sich in einer Crash-Schleife befindet, beheben Sie zuerst die zugrunde liegende Ursache. Erst danach sollten Sie erwägen, den betroffenen Dienst im Rahmen Ihres normalen Änderungsverfahrens neu zu starten. Ein Neustart kann Anfragen unterbrechen und wichtige Laufzeitinformationen entfernen. Stellen Sie daher vorher sicher, dass Sie dazu berechtigt sind, und sichern Sie relevante Protokolle.

3. Proxy-Fehlerprotokoll lesen

Gleichen Sie den Zeitstempel im Protokoll mit einer fehlgeschlagenen Anfrage ab. Prüfen Sie bei Nginx das konfigurierte Fehlerprotokoll, häufig /var/log/nginx/error.log. Bei Apache mit mod_proxy oder mod_proxy_fcgi prüfen Sie das Apache-Fehlerprotokoll.

Nützliche Unterscheidungen sind:

• connect() failed: Der Proxy kann den konfigurierten Upstream nicht erreichen.
• upstream timed out: Das Backend oder eine seiner Abhängigkeiten ist zu langsam oder überlastet.
• upstream sent too big header: Die Response-Header überschreiten die konfigurierten Proxy-Puffer.
• Ein Fehler beim Lesen der Statuszeile: Das Backend hat die Verbindung geschlossen oder eine ungültige Antwort zurückgegeben.

Der genaue Speicherort des Protokolls und das Format der Meldungen hängen vom Server und der Hosting-Plattform ab.

4. Upstream-Host, -Port oder Socket prüfen

Überprüfen Sie die Konfiguration des Reverse Proxys. Prüfen Sie bei Nginx den Block proxy_pass oder upstream. Prüfen Sie bei Apache ProxyPass, ProxyPassMatch und die Verbindungseinstellungen von PHP-FPM.

Verwenden Sie bei Bedarf eine schreibgeschützte Prüfung der Listener und eine lokale Anfrage:

ss -tlnp
curl http://127.0.0.1:PORT

Ersetzen Sie PORT durch den konfigurierten Anwendungsport. Wenn die Anwendung einen Unix-Socket verwendet, prüfen Sie, ob der Pfad existiert und der Proxy-Prozess darauf zugreifen kann. Bei PHP-FPM muss die Einstellung listen des Pools mit der in Apache oder Nginx konfigurierten Adresse beziehungsweise dem Socket übereinstimmen. Machen Sie einen internen Test-Endpunkt nicht eigens für diese Prüfung öffentlich zugänglich.

5. Überlastung, Abhängigkeiten und Timeouts untersuchen

Wenn das Backend läuft, die Fehler aber mit Traffic-Spitzen oder langsamen Anfragen zusammenfallen, prüfen Sie CPU, Arbeitsspeicher, Worker-Anzahl, Datenbankverbindungen, Warteschlangentiefe und Ressourcenlimits des Hosting-Panels. Ein Prozess kann laufen, ohne weitere Arbeit annehmen zu können.

Erhöhen Sie Proxy-Timeouts oder Puffergrößen nicht ohne entsprechende Anhaltspunkte. Wenn das Protokoll zu große Header meldet, untersuchen Sie die Antwort der Anwendung und prüfen Sie die relevanten Nginx-Einstellungen proxy_buffer_size und proxy_buffers. Falls eine Konfigurationsänderung erforderlich ist, validieren Sie sie und wenden Sie sie über das genehmigte Änderungsverfahren an, statt einen Produktions-Proxy ohne Autorisierung neu zu laden.

6. Origin- und CDN-Pfad vergleichen

Wenn Cloudflare oder ein anderes CDN der Website vorgeschaltet ist, testen Sie den Origin mit der korrekten Origin-Adresse und dem Host-Header direkt, sofern Sie dazu berechtigt sind. Vergleichen Sie das Ergebnis mit der öffentlichen Anfrage.

• Auch der Origin schlägt fehl: Untersuchen Sie Anwendung, Proxy, Socket, Port, Firewall und Ressourcenbedingungen am Origin.
• Der Origin funktioniert, aber das CDN schlägt fehl: Prüfen Sie CDN-zu-Origin-Firewallregeln, Erreichbarkeit des Origins, Routing und den Origin-SSL/TLS-Modus des CDNs. Stellen Sie sicher, dass der Origin das vom CDN erwartete Protokoll und die erwartete Zertifikatskonfiguration bereitstellt.

7. Nach der Fehlerbehebung erneut testen

Stellen Sie zunächst sicher, dass der Origin die erwartete Antwort zurückgibt. Testen Sie die Anfrage anschließend über den Reverse Proxy oder das CDN. Wenn nur einige URLs fehlschlagen, vergleichen Sie deren Anwendungsrouten, Antwortgröße, Authentifizierungsanforderungen und Backend-Abhängigkeiten, anstatt das Problem als allgemeinen Ausfall zu behandeln.

8. Limits des Hosting-Panels prüfen

Prüfen Sie bei cPanel, Plesk oder vergleichbarem Shared Hosting die PHP-FPM- und Ressourcenverbrauchsprotokolle. Das Konto erreicht möglicherweise ein vom Anbieter festgelegtes Limit für Prozesse, Arbeitsspeicher oder Nebenläufigkeit. Wenn das Limit nicht geändert werden kann, teilen Sie dem Hoster die Zeitpunkte der Fehler, die betroffene Route und die relevante Protokollmeldung mit, damit er Infrastrukturprotokolle prüfen kann.

Vorbeugung und Überprüfung der Lösung

• Betreiben Sie die Anwendung unter Prozessüberwachung und überwachen Sie wiederholte Abstürze, statt sich ausschließlich auf automatische Neustarts zu verlassen.
• Überwachen Sie Arbeitsspeicher, CPU, Worker-Auslastung, Datenbankverbindungen, Warteschlangentiefe und Hosting-Panel-Limits, bevor sie Anfragen beeinträchtigen.
• Legen Sie bewusste und kompatible Timeouts zwischen Anwendung, Proxy, Load Balancer und CDN fest. Verwenden Sie keine längeren Timeouts, um ein fehlerhaftes Backend zu verbergen.
• Überprüfen Sie nach Deployments und Konfigurationsänderungen den erwarteten Anwendungsport oder Socket.
• Testen Sie repräsentative Routen nach Änderungen an Origin-TLS, Firewallregeln oder Proxy-Konfiguration direkt gegen den Origin und über das CDN.
• Bewahren Sie Proxy- und Anwendungsprotokolle mit synchronisierten Zeitstempeln auf, damit sporadische 502-Antworten Backend-Ereignissen zugeordnet werden können.
• Dokumentieren Sie für die Umgebung den zuständigen Dienst, die Upstream-Adresse, Socket-Berechtigungen und das genehmigte Wiederherstellungsverfahren.

Häufig gestellte Fragen