Ctrlk
KundenbereichKundenservice
instagram
For the complete documentation index, see llms.txt. This page is also available as Markdown.

502 Bad Gateway beheben

Ein 502 Bad Gateway Fehler tritt meistens auf, wenn ein Webserver eine Anfrage nicht korrekt an den dahinterliegenden Dienst weiterleiten kann.

Der Fehler erscheint häufig bei Webseiten, die über Nginx, Apache, PHP-FPM, Node.js, Docker, Plesk, ein Webpanel oder eine eigene Anwendung betrieben werden.

Was bedeutet 502 Bad Gateway?

Ein Webserver nimmt die Anfrage eines Besuchers entgegen und leitet sie an einen anderen Dienst weiter.

Beispiele:

  • Nginx leitet an PHP-FPM weiter

  • Nginx leitet an eine Node.js App weiter

  • Apache leitet an PHP weiter

  • ein Reverse Proxy leitet an Docker weiter

  • ein Webpanel leitet an einen internen Dienst weiter

Wenn dieser dahinterliegende Dienst nicht antwortet, nicht läuft oder falsch erreichbar ist, zeigt der Webserver häufig den Fehler 502 Bad Gateway.

Typische Ursachen

Ein 502 Fehler kann mehrere Ursachen haben.

Häufige Gründe sind:

  • Anwendung läuft nicht

  • PHP-FPM läuft nicht

  • Node.js Prozess ist abgestürzt

  • falscher interner Port

  • falscher Proxy-Pfad

  • Docker Container ist gestoppt

  • Webserver-Konfiguration ist fehlerhaft

  • Dienst antwortet zu langsam

  • Socket-Datei existiert nicht

  • Firewall blockiert interne Verbindung

  • Server ist überlastet

  • Arbeitsspeicher ist voll

Unterschied zwischen 502, 503 und 504

Diese Fehler sehen ähnlich aus, bedeuten aber nicht genau dasselbe.

Fehler
Bedeutung

502 Bad Gateway

Der Webserver erhält eine ungültige oder keine passende Antwort vom Backend

503 Service Unavailable

Der Dienst ist nicht verfügbar oder absichtlich deaktiviert

504 Gateway Timeout

Der Backend-Dienst antwortet nicht rechtzeitig

Bei 502 Bad Gateway solltest du zuerst prüfen, ob der dahinterliegende Dienst läuft und ob der Webserver ihn korrekt erreichen kann.

Erste Prüfung

Prüfe zuerst, ob dein Server grundsätzlich erreichbar ist.

Öffne die Webseite im Browser und teste zusätzlich:

  • funktioniert die Domain?

  • zeigt die Domain auf die richtige IP-Adresse?

  • tritt der Fehler bei allen Seiten auf?

  • tritt der Fehler nur bei einer bestimmten Anwendung auf?

  • wurde kurz vorher etwas geändert?

  • wurde ein Update durchgeführt?

  • wurde eine Konfiguration angepasst?

Wenn der Fehler direkt nach einer Änderung aufgetreten ist, liegt die Ursache häufig in dieser Änderung.

Webserver-Status prüfen

Je nach System nutzt du Nginx oder Apache.

Nginx prüfen

Status prüfen:

systemctl status nginx

Konfiguration testen:

nginx -t

Nginx neu laden:

systemctl reload nginx

Nginx neu starten:

systemctl restart nginx

Wenn nginx -t einen Fehler ausgibt, muss zuerst die Konfiguration korrigiert werden.

Apache prüfen

Status prüfen:

systemctl status apache2

Konfiguration testen:

apachectl configtest

Apache neu laden:

systemctl reload apache2

Apache neu starten:

systemctl restart apache2

Bei AlmaLinux oder Rocky Linux kann der Apache-Dienst auch httpd heißen.

Status prüfen:

systemctl status httpd

Konfiguration testen:

httpd -t

Logs prüfen

Logs sind bei einem 502 Fehler besonders wichtig.

Sie zeigen meistens, welcher Dienst nicht erreichbar ist oder welche Datei fehlt.

Nginx Logs

Fehlerlog prüfen:

tail -n 100 /var/log/nginx/error.log

Live mitlesen:

tail -f /var/log/nginx/error.log

Apache Logs

Fehlerlog prüfen:

tail -n 100 /var/log/apache2/error.log

Bei AlmaLinux oder Rocky Linux:

tail -n 100 /var/log/httpd/error_log

Systemlogs prüfen

Systemmeldungen anzeigen:

journalctl -xe

Logs eines bestimmten Dienstes anzeigen:

journalctl -u nginx

journalctl -u apache2

journalctl -u php8.2-fpm

Der Name des PHP-FPM-Dienstes kann je nach Version abweichen.

PHP-FPM prüfen

Viele 502 Fehler entstehen, weil PHP-FPM nicht läuft oder falsch eingebunden ist.

PHP-FPM ist ein Dienst, der PHP-Dateien verarbeitet. Nginx leitet PHP-Anfragen häufig an PHP-FPM weiter.

Status prüfen:

systemctl status php-fpm

Je nach Distribution und PHP-Version kann der Dienst anders heißen.

Beispiele:

  • php-fpm

  • php8.1-fpm

  • php8.2-fpm

  • php8.3-fpm

Status prüfen:

systemctl status php8.2-fpm

PHP-FPM neu starten:

systemctl restart php8.2-fpm

Wenn du nicht weißt, wie der Dienst heißt, kannst du danach suchen:

systemctl list-units --type=service | grep fpm

PHP-FPM Socket prüfen

Bei Nginx wird PHP-FPM oft über eine Socket-Datei verbunden.

Ein typischer Eintrag sieht so aus:

fastcgi_pass unix:/run/php/php8.2-fpm.sock;

Wenn diese Datei nicht existiert, kann Nginx PHP nicht erreichen und zeigt häufig 502 Bad Gateway.

Socket-Dateien prüfen:

ls -lah /run/php/

Wenn deine Nginx-Konfiguration auf php8.1-fpm.sock zeigt, aber auf dem Server nur php8.2-fpm.sock existiert, muss die Konfiguration angepasst werden.

Danach Nginx testen und neu laden:

nginx -t

systemctl reload nginx

Node.js Anwendung prüfen

Wenn deine Webseite über Node.js läuft, muss die Anwendung im Hintergrund aktiv sein.

Prüfe zuerst, ob der Prozess läuft.

Prozesse anzeigen:

ps aux | grep node

Wenn du PM2 verwendest:

pm2 status

Logs anzeigen:

pm2 logs

App neu starten:

pm2 restart all

Wenn deine App auf Port 3000 laufen soll, prüfe, ob dieser Port belegt ist:

ss -tulpen | grep 3000

Wenn kein Dienst auf dem erwarteten Port läuft, kann Nginx nicht an deine App weiterleiten.

Reverse Proxy prüfen

Ein 502 Fehler tritt häufig bei Reverse-Proxy-Konfigurationen auf.

Beispiel für Nginx:

proxy_pass http://127.0.0.1:3000;

In diesem Fall muss deine Anwendung auf 127.0.0.1 und Port 3000 erreichbar sein.

Prüfen:

curl http://127.0.0.1:3000

Wenn dieser Befehl keine Antwort liefert, liegt das Problem nicht bei der Domain, sondern bei deiner Anwendung oder dem internen Dienst.

Docker Container prüfen

Wenn deine Anwendung in Docker läuft, prüfe zuerst die Container.

Container anzeigen:

docker ps

Alle Container anzeigen:

docker ps -a

Logs anzeigen:

docker logs CONTAINERNAME

Container starten:

docker start CONTAINERNAME

Container neu starten:

docker restart CONTAINERNAME

Wenn du Docker Compose nutzt:

docker compose ps

docker compose logs

docker compose restart

Ein 502 Fehler entsteht häufig, wenn der Container gestoppt ist oder der Webserver auf einen falschen Container-Port zeigt.

Port-Zuordnung bei Docker prüfen

Bei Docker muss die Port-Zuordnung stimmen.

Beispiel:

127.0.0.1:3000 -> Container-Port 3000

Wenn deine Anwendung im Container auf Port 8080 läuft, der Reverse Proxy aber auf Port 3000 zeigt, entsteht ein Fehler.

Prüfe deshalb:

  • auf welchem Port läuft die Anwendung im Container?

  • welcher Port ist nach außen gebunden?

  • auf welchen Port zeigt Nginx oder Apache?

  • wurde der Container neu erstellt und der Port geändert?

Anwendung ist abgestürzt

Wenn der Webserver funktioniert, aber die Anwendung abgestürzt ist, erscheint ebenfalls oft 502 Bad Gateway.

Typische Ursachen:

  • fehlende Umgebungsvariablen

  • falsche Datenbankdaten

  • fehlende Dateien

  • fehlerhafte Abhängigkeiten

  • zu wenig Arbeitsspeicher

  • Syntaxfehler nach Update

  • falsche Node.js-, PHP- oder Python-Version

Prüfe die Logs der Anwendung.

Beispiele:

pm2 logs

docker logs CONTAINERNAME

journalctl -u DIENSTNAME

Speicher und Auslastung prüfen

Wenn der Server überlastet ist, können Dienste abstürzen oder nicht mehr antworten.

CPU und RAM prüfen:

top

oder:

htop

Speicherplatz prüfen:

df -h

Arbeitsspeicher prüfen:

free -h

Wenn der Speicherplatz voll ist, können Dienste keine temporären Dateien oder Logs mehr schreiben. Das kann zu Fehlern führen.

Rechte und Dateipfade prüfen

Bei Webanwendungen können falsche Rechte ebenfalls Probleme verursachen.

Prüfe:

  • existiert der angegebene Pfad?

  • darf der Webserver auf die Dateien zugreifen?

  • gehören die Dateien dem richtigen Benutzer?

  • sind Socket-Dateien erreichbar?

  • wurde ein Ordner verschoben oder gelöscht?

Typische Webserver-Benutzer sind:

  • www-data

  • nginx

  • apache

Nach Updates prüfen

Ein 502 Fehler tritt oft nach Updates auf.

Mögliche Beispiele:

  • PHP-Version wurde geändert

  • PHP-FPM Socket hat sich geändert

  • Node.js Version passt nicht mehr

  • Composer-Abhängigkeiten fehlen

  • npm-Abhängigkeiten fehlen

  • Webserver-Konfiguration wurde überschrieben

  • Docker Image wurde aktualisiert

  • Datenbank ist nicht mehr erreichbar

Wenn der Fehler nach einem Update auftritt, prüfe zuerst die geänderten Dienste und Logs.

Datenbankverbindung prüfen

Viele Anwendungen benötigen eine Datenbank.

Wenn die Datenbank nicht erreichbar ist, kann die Anwendung abstürzen und der Webserver zeigt einen 502 Fehler.

Datenbankstatus prüfen:

MariaDB oder MySQL:

systemctl status mariadb

oder:

systemctl status mysql

PostgreSQL:

systemctl status postgresql

Wenn die Datenbank nicht läuft, starte sie neu:

systemctl restart mariadb

systemctl restart mysql

systemctl restart postgresql

Prüfe danach die Logs der Anwendung.

Firewall prüfen

Bei lokalen Verbindungen ist die Firewall meistens nicht das Problem. Wenn dein Backend aber auf einer anderen IP-Adresse oder einem anderen Server läuft, kann eine Firewall die Verbindung blockieren.

Prüfe:

  • ist der Zielport geöffnet?

  • ist die Ziel-IP erreichbar?

  • erlaubt die Firewall die Verbindung?

  • zeigt die Konfiguration auf die richtige IP-Adresse?

UFW Status prüfen:

ufw status

Typische Fehlermeldungen in Nginx

Nginx zeigt in den Logs oft genaue Hinweise.

Meldung
Bedeutung

connect() failed (111: Connection refused)

Backend-Dienst läuft nicht oder falscher Port

upstream timed out

Backend antwortet zu langsam

no such file or directory

Socket-Datei oder Pfad fehlt

permission denied

Rechteproblem

bad gateway

Backend liefert keine passende Antwort

Wenn du eine dieser Meldungen findest, kannst du die Ursache meist direkt eingrenzen.

Schritt-für-Schritt Fehlerbehebung

Gehe bei einem 502 Fehler am besten in dieser Reihenfolge vor:

  1. Prüfe, ob der Fehler bei allen Seiten auftritt.

  2. Prüfe den Webserver-Status.

  3. Teste die Webserver-Konfiguration.

  4. Prüfe die Error-Logs.

  5. Prüfe den Backend-Dienst.

  6. Prüfe PHP-FPM, Node.js, Docker oder die jeweilige Anwendung.

  7. Prüfe interne Ports oder Socket-Dateien.

  8. Prüfe Speicherplatz und Arbeitsspeicher.

  9. Prüfe Änderungen oder Updates.

  10. Starte betroffene Dienste neu.

Dienste neu starten

Wenn du die Ursache eingegrenzt hast, kannst du die betroffenen Dienste neu starten.

Nginx:

systemctl restart nginx

Apache:

systemctl restart apache2

PHP-FPM:

systemctl restart php8.2-fpm

Node.js mit PM2:

pm2 restart all

Docker Compose:

docker compose restart

Starte nicht blind alle Dienste neu, ohne Logs zu prüfen. Sonst verschwinden wichtige Hinweise aus aktiven Prozessen.

Wenn du Plesk oder ein Webpanel nutzt

Wenn du ein Webpanel wie Plesk, aaPanel oder ein anderes Verwaltungspanel nutzt, kann der 502 Fehler auch durch die Panel-Konfiguration entstehen.

Prüfe dort:

  • Webserver-Einstellungen

  • PHP-Version

  • PHP-FPM Status

  • Domain-Konfiguration

  • SSL-Einstellungen

  • Proxy-Einstellungen

  • Logs der Domain

Ändere keine Einstellungen, wenn du nicht sicher bist, welche Funktion sie haben.

Support kontaktieren

Wenn du den Fehler nicht selbst beheben kannst, kontaktiere den Support.

Gib dabei möglichst genau an:

  • betroffene Domain

  • Server-IP

  • Betriebssystem

  • verwendeter Webserver

  • verwendete Anwendung

  • seit wann der Fehler auftritt

  • ob vorher Änderungen vorgenommen wurden

  • relevante Fehlermeldungen aus den Logs

  • ob du PHP-FPM, Node.js, Docker oder ein Webpanel nutzt

Sende keine Passwörter, privaten SSH-Keys, API-Tokens oder andere geheime Zugangsdaten an den Support.

Vorherige404 Not Found behebenNächsteWindows

Zuletzt aktualisiert