502 Bad Gateway: was es wirklich bedeutet und wie man es behebt

Sie öffnen Ihre Website und statt Inhalten sehen Sie eine leere Seite mit der Meldung 502 Bad Gateway. Das sieht beängstigend aus, aber in den meisten Fällen ist die Lösung einfach. Lassen Sie uns aufschlüsseln, was passiert und wie Sie Ihre Website wieder zum Laufen bringen.

Was bedeutet 502 eigentlich?

Wenn ein Besucher eine Seite anfordert, durchläuft die Anfrage normalerweise zwei Ebenen: einen Frontend-Webserver (normalerweise Nginx) und einen Backend-Anwendungsserver (PHP-FPM, Apache, Node.js oder etwas anderes). Nginx empfängt die Anfrage, leitet sie an das Backend weiter und wartet auf eine Antwort.

Ein 502 Bad Gateway bedeutet, dass Nginx versucht hat, eine Antwort vom Backend zu erhalten, aber etwas Ungültiges erhalten oder gar keine Antwort erhalten hat. Das Backend ist entweder abgestürzt, hat die Verbindung verweigert oder etwas zurückgegeben, mit dem Nginx nichts anfangen konnte.

info

Ein häufiges Missverständnis: 502 bedeutet nicht, dass Ihr Server ausgefallen ist. Der Server selbst ist in Ordnung – es ist die Anwendung hinter Nginx, die Probleme hat.

Häufigste Ursachen

Der Backend-Dienst wurde beendet. Das ist der Hauptgrund. PHP-FPM ist abgestürzt, Apache hängt oder ein Node.js-Prozess wurde stillschweigend beendet. Nginx hat nichts zum Kommunizieren.

Der Server läuft aus dem RAM. Wenn der Arbeitsspeicher knapp wird, kann Linux ressourcenintensive Prozesse automatisch beenden. Dieser Mechanismus wird OOM Killer (Out-Of-Memory Killer) genannt, und PHP-FPM oder MySQL sind normalerweise seine ersten Opfer. Wenn dies regelmäßig vorkommt, sollten Sie eine Swap-Datei hinzufügen als Sicherheitsnetz in Betracht ziehen.

PHP-FPM Worker-Pool ist erschöpft. Wenn Ihre Website mehr gleichzeitige Anfragen erhält, als PHP-FPM verarbeiten kann, werden neue Anfragen in die Warteschlange gestellt und laufen schließlich ab. Dies geschieht häufig, wenn Suchmaschinen-Bots Ihre Website zu aggressiv crawlen – wir haben darüber in unserem Bot-Blockierungsleitfaden geschrieben.

Falsch konfigurierter Socket oder Port. Nginx erwartet, PHP-FPM über einen bestimmten Unix-Socket oder TCP-Port zu finden. Wenn der Pfad in der Nginx-Konfiguration nicht mit der PHP-FPM-Konfiguration übereinstimmt, sehen Sie sofort nach jeder Änderung 502-Fehler.

Diagnose

Um die folgenden Schritte auszuführen, verbinden Sie sich über SSH mit Ihrem Server. Wie Sie das tun, erfahren Sie in unserem SSH-Artikel.

Schritt 1. Prüfen Sie, ob das Backend läuft

Prüfen Sie den Status Ihres Backend-Dienstes:

sudo systemctl status php8.2-fpm

Ersetzen Sie php8.2-fpm durch Ihre tatsächliche PHP-Version oder den Namen Ihres Backend-Dienstes. Wenn die Ausgabe inactive (dead) oder failed anzeigt, ist das Ihr Problem. Starten Sie ihn neu:

sudo systemctl restart php8.2-fpm

Überprüfen Sie dann erneut den Status, um sicherzustellen, dass er erfolgreich gestartet wurde.

Schritt 2. Prüfen Sie das Nginx-Fehlerprotokoll

Das Fehlerprotokoll sagt Ihnen fast immer genau, was schiefgelaufen ist:

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

Wenn Sie FASTPANEL® verwenden, können Sie Protokolle auch direkt in der Weboberfläche einsehen: Öffnen Sie die Site-Karte, gehen Sie zum Abschnitt „Logs“ und prüfen Sie den Tab „Frontend Error Log“.

Hier sind die häufigsten Fehlermeldungen und ihre Bedeutung:

connect() failed - Connection refused – der Backend-Dienst läuft nicht. Starten Sie ihn neu wie in Schritt 1 gezeigt.

connect() failed - No such file or directory – Nginx versucht, auf einen Unix-Socket zuzugreifen, der nicht existiert. Prüfen Sie, ob der Socket-Pfad in Ihrer Nginx-Konfiguration mit dem übereinstimmt, was PHP-FPM tatsächlich erstellt.

upstream sent too big header – das Backend hat HTTP-Header zurückgegeben, die zu groß für den Standardpuffer sind. Fügen Sie diese Zeilen zu Ihrer Nginx-Site-Konfiguration innerhalb des server-Blocks hinzu:

fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;

Nach der Bearbeitung testen Sie die Konfiguration und laden Sie Nginx neu:

sudo nginx -t && sudo systemctl reload nginx

Schritt 3. Prüfen Sie die Serverressourcen

free -h

Wenn die Spalte available weniger als 100–200 MB freien Speicher anzeigt, läuft Ihr Server wahrscheinlich aus dem RAM. Prüfen Sie, was den Speicher verbraucht:

ps aux --sort=-%mem | head -10

warnung

Wenn Speicherdruck die Ursache ist, ist die schnellste temporäre Lösung das Hinzufügen einer Swap-Datei. Swap auf der Festplatte ist jedoch viel langsamer als RAM und sollte nicht als dauerhafte Lösung betrachtet werden. Wenn Ihr Server regelmäßig zu wenig Speicher hat, ist es an der Zeit, Ihre Anwendungen zu optimieren oder auf einen Plan mit mehr RAM aufzurüsten.

Fazit

Ein 502 Bad Gateway ist fast immer ein Backend-Problem – ein abgestürzter Dienst, erschöpfte Worker oder zu wenig Speicher. Überprüfen Sie den Backend-Status, lesen Sie das Nginx-Fehlerprotokoll und prüfen Sie Ihre Ressourcenauslastung. In den allermeisten Fällen finden Sie die Antwort innerhalb von Minuten.

Wenn Sie sich lieber nicht allein damit befassen möchten, bieten wir bei kodu.cloud kostenlosen technischen Support rund um die Uhr für jeden VPS und dedizierten Server an. Alle unsere Kunden erhalten zudem FASTPANEL® Extended ohne zusätzliche Kosten, was die Protokollanalyse und die Dienstverwaltung über eine Weboberfläche erheblich erleichtert.