502 Bad Gateway: Ursache finden und beheben

Was der Fehler bedeutet

Ein 502 ist die Antwort eines Servers, der funktioniert. Der Webserver vorne (nginx, Apache, ein Load Balancer oder ein CDN wie Cloudflare) hat die Anfrage bekommen, sie an die Anwendung dahinter weitergereicht (PHP-FPM, ein Node.js- oder Python-Prozess, ein Backend-Server) und keine brauchbare Antwort zurückbekommen: Verbindung verweigert, abgebrochen oder Unsinn geliefert. „Gateway“ ist der Server vorne, „bad“ ist das, was von hinten kam.

Ein 502 sagt dir also zwei Dinge auf einmal: Vorne läuft es, hinten ist etwas gestoppt oder kaputt. Das grenzt die Suche deutlich ein.

Häufige Ursachen

1. Der Anwendungsprozess läuft nicht. PHP-FPM ist abgestürzt oder wurde gestoppt, der Node.js-Prozess ist tot, der Container beendet. Vorne kommt gar keine Verbindung zustande.
2. Die Anwendung ist überlastet. Alle PHP-FPM-Worker sind beschäftigt, die Warteschlange ist voll, neue Verbindungen werden abgewiesen. Oft nach einer Besucherspitze oder einer langsamen Datenbankabfrage, die alle Worker blockiert.
3. Falscher Socket oder Port in der Konfiguration. Nach einem Update oder PHP-Versionswechsel zeigt nginx noch auf php8.2-fpm.sock, der neue Pool lauscht aber auf php8.4-fpm.sock.
4. Zu knappe Timeouts. Das Backend antwortet, aber später, als der Webserver warten will. Manche Setups melden das als 502, andere als 504 Gateway Timeout.
5. Das Backend schickt zu große Header oder eine ungültige Antwort. Typisch für Frameworks, die viel in Cookies packen; nginx protokolliert dann „upstream sent too big header“.
6. Das CDN erreicht deinen Server nicht. Mit Cloudflare davor heißt eine 502-Seite mit Cloudflare-Logo: Cloudflare hat von deinem Server nichts bekommen. Firewall, falsche IP nach einem Umzug, oder der Server ist schlicht aus.

Wenn du Besucher bist

Einen 502 auf einer fremden Website kannst du nicht beheben. Lade nach einer Minute einmal neu; bleibt er, muss der Betreiber ran. Für deine eigene Website lies weiter.

Wenn es deine Website ist: zuerst prüfen

Ist sie für alle down? Lass den Website-Down-Checker laufen. Er zeigt den Statuscode von außen und ob ein CDN oder dein Server geantwortet hat.

Shared Hosting oder Baukasten? Ein 502 ist dort fast immer ein Problem des Hosters (ein überlasteter PHP-Pool auf einem geteilten Server). Spring zum fertigen Text für deinen Hoster weiter unten.

Eigener Server: Per SSH anmelden und den Webserver fragen, was schiefging.

# nginx: die letzten Fehler, die neuesten unten
sudo tail -n 50 /var/log/nginx/error.log

# Apache (Debian/Ubuntu)
sudo tail -n 50 /var/log/apache2/error.log

Typische Zeilen und ihre Bedeutung:

• connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory): PHP-FPM läuft nicht, oder der Socket-Pfad ist falsch.
• connect() failed (111: Connection refused) while connecting to upstream: Auf dem Backend-Port lauscht nichts.
• upstream prematurely closed connection: Der Backend-Prozess ist beim Antworten abgestürzt, meist ein PHP-Fatal-Error oder zu wenig Speicher.
• upstream sent too big header: Puffer vergrößern (siehe unten).
• (11: Resource temporarily unavailable): Alle PHP-FPM-Worker sind beschäftigt.

Lösungen auf deinem eigenen Server

1. Den gestoppten Dienst starten

# welche PHP-FPM-Version läuft bei dir?
systemctl list-units --type=service | grep -E 'php|fpm'

systemctl status php8.3-fpm
sudo systemctl start php8.3-fpm

# Node.js- oder Python-Anwendungen unter systemd
sudo systemctl restart meine-app

Startet der Dienst nicht, steht der Grund in journalctl -u php8.3-fpm -n 50. Am häufigsten: eine volle Festplatte (df -h), danach ein Syntaxfehler in einer Pool-Konfiguration (sudo php-fpm8.3 -t).

2. Socket oder Port richtigstellen

Vergleiche, wohin nginx verbindet, mit dem, worauf PHP-FPM lauscht:

grep -r fastcgi_pass /etc/nginx/sites-enabled/
grep -r '^listen' /etc/php/*/fpm/pool.d/

Beides muss übereinstimmen. Nach einer Änderung immer erst die Konfiguration testen, dann neu laden:

sudo nginx -t && sudo systemctl reload nginx

Bei Apache mit PHP-FPM über mod_proxy_fcgi gilt dasselbe für die Zeile SetHandler "proxy:unix:/run/php/php8.3-fpm.sock|fcgi://localhost"; Test mit sudo apachectl configtest.

3. PHP-FPM Luft verschaffen

Meldet das Fehlerprotokoll beschäftigte Worker oder server reached pm.max_children, erhöhe die Grenze in der Pool-Datei (/etc/php/8.3/fpm/pool.d/www.conf):

pm = dynamic
pm.max_children = 20
pm.start_servers = 4
pm.min_spare_servers = 2
pm.max_spare_servers = 6

Jeder Worker braucht Arbeitsspeicher (bei WordPress oft 30 bis 80 MB); prüf free -m, bevor du die Zahl erhöhst, und such die langsame Abfrage oder das Plugin, das die Worker überhaupt erst blockiert.

4. Puffer für große Header erhöhen

Im nginx-Server-Block:

fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;
proxy_buffers 8 16k;
proxy_buffer_size 32k;

5. Besonderheiten bei WordPress

Ein 502 direkt nach einem Plugin- oder Theme-Update heißt meist: PHP läuft bei jeder Anfrage in einen Speicher- oder Fatal-Fehler. Benenn den Plugin-Ordner per SFTP oder SSH um, um es abzuschalten (wp-content/plugins/plugin-name zu plugin-name.off), und lade die Seite neu. Erhöhe memory_limit im Pool oder in der php.ini, wenn journalctl „Allowed memory size exhausted“ zeigt. Mit der WP-CLI: wp plugin deactivate plugin-name.

6. Hinter Cloudflare

Prüf, ob der Ursprungsserver direkt antwortet: curl -I https://DEINE-SERVER-IP -H 'Host: example.com' -k. Klappt das, blockiert vielleicht die Firewall auf dem Server die Adressbereiche von Cloudflare, oder der DNS-Eintrag bei Cloudflare zeigt auf eine alte IP.

Wenn es ein Problem deines Hosters ist

Im Shared Hosting kannst du PHP-FPM nicht neu starten. Schick deinem Hoster das hier, mit Uhrzeit und genauer Fehlermeldung:

Guten Tag, meine Website example.com liefert seit etwa 14:30 Uhr (UTC) „502 Bad Gateway“. Eine Prüfung von außen bestätigt das; ich habe auf meiner Seite nichts geändert. Könnten Sie bitte die PHP-Prozesse und den Webserver meines Hosting-Kontos prüfen und mir sagen, wann die Seite wieder läuft?

Damit es nicht wieder passiert

Ein 502 ist fast immer ein gestopptes oder überlastetes Backend, und beides ist sichtbar, bevor Besucher es merken: ein PHP-FPM-Dienst, der gestoppt hat, knapper Arbeitsspeicher, eine vollaufende Festplatte. Das Server-Monitoring mit dem Agent meldet genau das aus dem Server heraus, und Website-Prüfungen von außen erwischen den 502 in dem Moment, in dem er auftaucht. Auf deinem eigenen Server startet der Schnelleingriff den gestoppten Dienst neu, wenn sein Konfigurationstest besteht; liegt die Ursache tiefer, übernimmt der Intensiveingriff, rund um die Uhr.