502 Bad Gateway: was es tatsächlich bedeutet und wie Sie es beheben

Sie öffnen Ihre Website und statt Inhalten sehen Sie eine leere Seite mit der Meldung 502 Bad Gateway. Das wirkt beängstigend, aber in den meisten Fällen ist die Behebung unkompliziert. Sehen wir uns an, was passiert und wie Sie Ihre Website wieder online bringen.

Was bedeutet 502 eigentlich?

Wenn ein Besucher eine Seite anfordert, durchläuft die Anfrage typischerweise zwei Ebenen: einen Frontend-Webserver (meist 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 empfangen hat oder überhaupt keine Antwort bekommen hat. Das Backend ist entweder abgestürzt, hat die Verbindung verweigert oder etwas zurückgegeben, das Nginx nicht interpretieren konnte.

info

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

Häufigste Ursachen

Der Backend-Dienst wurde beendet. Das ist der häufigste Grund. PHP-FPM ist abgestürzt, Apache hängt oder ein Node.js-Prozess wurde stillschweigend beendet. Nginx hat nichts, womit es kommunizieren kann.

Dem Server geht der RAM aus. Wenn der Arbeitsspeicher knapp wird, kann Linux ressourcenintensive Prozesse automatisch beenden. Dieser Mechanismus wird OOM killer genannt, und PHP-FPM oder MySQL sind meist seine ersten Opfer. Wenn das regelmäßig passiert, ziehen Sie in Betracht, als Sicherheitsnetz eine Swap-Datei hinzuzufügen.

Der PHP-FPM-Worker-Pool ist ausgeschöpft. Wenn Ihre Website mehr gleichzeitige Anfragen erhält, als PHP-FPM verarbeiten kann, werden neue Anfragen in eine Warteschlange gestellt und laufen schließlich in ein Timeout. Das passiert häufig, wenn Suchmaschinen-Bots Ihre Website zu aggressiv crawlen - darüber, wie man damit umgeht, haben wir in unserem Leitfaden zum Blockieren von Bots geschrieben.

Socket oder Port falsch konfiguriert. Nginx erwartet, PHP-FPM an einem bestimmten Unix-Socket oder TCP-Port zu finden. Wenn der Pfad in der Nginx-Konfiguration nicht mit der PHP-FPM-Konfiguration übereinstimmt, sehen Sie unmittelbar nach jeder Änderung 502-Fehler.

So diagnostizieren Sie das Problem

Um die folgenden Schritte auszuführen, verbinden Sie sich per SSH mit Ihrem Server. Wie das geht, 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 in der Ausgabe inactive (dead) oder failed steht, ist das Ihr Problem. Starten Sie ihn neu:

sudo systemctl restart php8.2-fpm

Prüfen Sie danach den Status erneut, um sicherzustellen, dass der Dienst erfolgreich gestartet wurde.

Schritt 2. Prüfen Sie das Nginx-Fehlerlog

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

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

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

Hier sind die häufigsten Fehlermeldungen und was sie bedeuten:

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

connect() failed - No such file or directory - Nginx versucht, einen Unix-Socket zu erreichen, 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 für den Standardpuffer zu groß sind. Fügen Sie diese Zeilen in Ihrer Nginx-Seitenkonfiguration innerhalb des Blocks server hinzu:

fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;

Testen Sie nach dem Bearbeiten 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, geht Ihrem Server wahrscheinlich der RAM aus. Prüfen Sie, was ihn verbraucht:

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

warnung

Wenn Speicherdruck die Hauptursache ist, ist die schnellste vorübergehende 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 Ihrem Server regelmäßig der Arbeitsspeicher ausgeht, ist es an der Zeit, entweder Ihre Anwendungen zu optimieren oder auf einen Tarif mit mehr RAM umzusteigen.

Fazit

Ein 502 Bad Gateway ist fast immer ein Backend-Problem - ein abgestürzter Dienst, ausgeschöpfte Worker oder zu wenig Speicher. Prüfen Sie den Backend-Status, lesen Sie das Nginx-Fehlerlog und sehen Sie sich Ihre Ressourcenauslastung an. In den allermeisten Fällen finden Sie die Antwort innerhalb weniger Minuten.

Wenn Sie sich lieber nicht allein darum kümmern möchten, bieten wir bei kodu.cloud kostenlosen technischen 24/7-Support zu jedem VPS und dedicated server an. Alle unsere Kunden erhalten außerdem FASTPANEL® Extended ohne zusätzliche Kosten, was die Log-Analyse und die Dienstverwaltung über eine Weboberfläche deutlich erleichtert.