> For the complete documentation index, see [llms.txt](https://docs.instantroot.de/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.instantroot.de/kvm-server/linux/502-bad-gateway-beheben.md). # 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.