PHP-FPM 502 Bad Gateway: Nginx und Socket prüfen

Deine Website funktioniert – bis nach einem PHP-Update plötzlich nur noch 502 Bad Gateway erscheint. Bei Nginx bedeutet das zunächst, dass die Kommunikation mit dem vorgeschalteten Dienst nicht erfolgreich war. Häufig steckt eine falsche Socket-Adresse, ein gestoppter PHP-FPM-Prozess oder eine fehlende Berechtigung dahinter. Ein 502-Fehler allein verrät aber noch nicht, welche dieser Ursachen tatsächlich vorliegt. Mit den folgenden Schritten grenzt du das Problem systematisch ein, bevor du irgendetwas an deinen Serverrechten veränderst.

Voraussetzungen: Nginx mit PHP-FPM auf Ubuntu oder Debian, Terminalzugriff mit passenden Rechten und möglichst ein Backup der Webserver- und PHP-FPM-Konfiguration. Die Beispielbefehle verwenden PHP 8.3 als Platzhalter; dein System kann eine andere Version nutzen. In Docker-Setups läuft PHP-FPM möglicherweise unter einem anderen Dienstnamen oder als TCP-Upstream im separaten Container.

1. Den Fehler bestätigen

Prüfe zuerst die Nginx-Konfiguration und lies die letzten Fehlerprotokolle. Der erste Befehl ist rein lesend und prüft die Syntax; der zweite zeigt Meldungen des Webservers.

sudo nginx -t
sudo journalctl -u nginx -n 80 --no-pager

Beispielausgabe (gekürzt, keine echte Messung):

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Nov 09 17:00:00 server nginx[1234]: [error] connect() to unix:/run/php/php8.2-fpm.sock failed (2: No such file or directory) while connecting to upstream

Die gezeigte Socket-Meldung ist ein Beispiel. In deinem Fall kann sie anders lauten. No such file or directory spricht bei der Verbindung zu einem Unix-Socket für einen fehlenden Socket oder falschen Pfad. Permission denied weist eher auf Zugriffsrechte hin. Ein Timeout oder Connection refused erfordert weitere Prüfungen.

2. PHP-FPM finden

Ermittle zunächst den tatsächlichen Dienstnamen. Ein gewöhnliches php -v zeigt nur die CLI-Version und beweist nicht, welche PHP-FPM-Version deine Website verwendet.

systemctl list-units 'php*-fpm.service' --all
ls -la /run/php/

Beispielausgabe (gekürzt, keine echte Messung):

UNIT                 LOAD   ACTIVE SUB     DESCRIPTION
php8.3-fpm.service   loaded active running The PHP 8.3 FastCGI Process Manager

srw-rw---- 1 www-data www-data 0 Nov 09 17:00 php8.3-fpm.sock

Ersetze im weiteren Verlauf php8.3-fpm durch die tatsächlich ausgegebene Dienstbezeichnung. Falls keine Unit vorhanden ist, prüfe, ob PHP-FPM überhaupt installiert ist, über Docker läuft oder einen abweichenden Dienstnamen besitzt. Eine Installation auf Verdacht ist keine gute Diagnose.

sudo systemctl status php8.3-fpm --no-pager
sudo journalctl -u php8.3-fpm -n 80 --no-pager

Beispielausgabe (gekürzt, keine echte Messung):

● php8.3-fpm.service - The PHP 8.3 FastCGI Process Manager
     Loaded: loaded
     Active: active (running)

Nov 09 17:00:00 server systemd[1]: Started php8.3-fpm.service.

Wenn failed oder inactive erscheint, beachte zuerst die konkrete FPM-Fehlermeldung. Mögliche Ursachen sind fehlerhafte Pool-Konfigurationen, belegte Ports, fehlende Verzeichnisse und Ressourcenprobleme. Starte den Dienst nicht endlos neu, ohne den Grund zu kennen.

3. Nginx und Socket vergleichen

Die entscheidende Einstellung heißt fastcgi_pass in Nginx beziehungsweise listen im PHP-FPM-Pool. Nginx kann auf einen Unix-Socket wie /run/php/php8.3-fpm.sock oder auf einen TCP-Endpunkt verweisen. Beide Seiten müssen zusammenpassen.

sudo nginx -T 2>&1 | grep -n 'fastcgi_pass'
sudo grep -R -E '^[[:space:]]*listen[[:space:]]*=' /etc/php/*/fpm/pool.d/

Beispielausgabe (gekürzt, keine echte Messung):

145: fastcgi_pass unix:/run/php/php8.2-fpm.sock;
/etc/php/8.3/fpm/pool.d/www.conf:listen = /run/php/php8.3-fpm.sock

Hier zeigt sich ein beispielhafter Versionskonflikt: Nginx verweist noch auf 8.2, obwohl der aktive Pool bereits auf 8.3 lauscht. Wenn du die Ursache so eindeutig belegen kannst, sichere die betroffene Nginx-Site-Datei und passe nur die betreffende fastcgi_pass-Zeile an. Kopiere keine komplette fremde Nginx-Konfiguration über deine funktionierende Site.

Die passenden Einträge könnten nach der Korrektur so aussehen. Es handelt sich um getrennte Konfigurationsausschnitte, nicht um ein gemeinsam einzufügendes Dokument:

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

Dazu passt im betreffenden PHP-FPM-Pool beispielsweise:

listen = /run/php/php8.3-fpm.sock

4. Berechtigungen sicher prüfen

Steht im Nginx-Fehlerprotokoll ausdrücklich Permission denied, prüfe zuerst Socket-Eigentümer, Gruppe und Zugriffsrechte sowie den effektiven Nginx-Worker-Benutzer. Auf einem typischen Debian-/Ubuntu-System kann dieser www-data heißen, aber das muss nicht so sein.

ls -l /run/php/*.sock
sudo nginx -T 2>&1 | grep -E '^user[[:space:]]'

Beispielausgabe (gekürzt, keine echte Messung):

srw-rw---- 1 www-data www-data 0 Nov 09 17:00 /run/php/php8.3-fpm.sock
user www-data;

Der PHP-FPM-Pool steuert Socket-Rechte unter anderem mit listen.owner, listen.group und listen.mode. Prüfe die vorhandenen Werte und passe sie ausschließlich an die tatsächlich benötigte Benutzer-/Gruppenkonstellation an. Setze niemals pauschal chmod 777 auf Sockets oder Konfigurationsverzeichnisse. Ein offen erreichbarer FastCGI-Endpunkt ist ein erhebliches Sicherheitsrisiko.

5. Konfiguration testen

Nach einer gezielten Änderung sollten beide Dienste ihre Konfigurationen prüfen können. Der Dateiname und die PHP-Version müssen zu deinem Server passen:

sudo nginx -t
sudo php-fpm8.3 -t

Beispielausgabe (gekürzt, keine echte Messung):

nginx: configuration file /etc/nginx/nginx.conf test is successful
[09-Nov-2026 17:00:00] NOTICE: configuration file /etc/php/8.3/fpm/php-fpm.conf test is successful

Bei einem Syntaxfehler nicht neu laden oder neu starten, sondern zunächst die gemeldete Datei und Zeilennummer korrigieren. Ist alles erfolgreich und wurde nur Nginx geändert, reicht in der Regel ein Reload von Nginx. Wenn du FPM-Pool-Einstellungen geändert hast, ist die FPM-Neustartplanung gesondert notwendig und kann laufende PHP-Anfragen unterbrechen.

sudo systemctl reload nginx
curl -I https://deine-domain.example

Beispielausgabe (gekürzt, keine echte Messung):

HTTP/2 200
server: nginx
content-type: text/html; charset=UTF-8

HTTP 200 ist nur eine mögliche erfolgreiche Antwort; eine gültige Anwendung kann beispielsweise auch zu ihrer Anmeldeseite weiterleiten. Teste daher zusätzlich eine tatsächlich dynamische PHP-Seite und den zuvor fehlgeschlagenen Anwendungsablauf. Die Domain in diesem Beispiel musst du ersetzen.

6. Wenn der Fehler bleibt

Sind Nginx- und Pool-Adressen korrekt und die Rechte plausibel, kommen Ressourcenmangel, abgestürzte Prozesse, überlastete Worker oder ein weiterer Upstream in Betracht. Unterscheide dabei einen 502-Fehler von einem 504-Timeout; beide erfordern nicht zwangsläufig dieselbe Maßnahme.

free -h
df -h
sudo journalctl -k -n 80 --no-pager
sudo journalctl -u php8.3-fpm -n 100 --no-pager

Beispielausgabe (gekürzt, keine echte Messung):

Mem:  7.7Gi  7.1Gi  190Mi  120Mi  430Mi  350Mi
Filesystem  Size  Used Avail Use% Mounted on
/dev/sda2    50G   47G  3.0G  94% /

[Beispiel: Hier nach OOM-, Speicher- oder FPM-Fehlern suchen]

Ein hoher Speicherdruck oder ein fast volles Dateisystem ist ein Hinweis, noch keine bewiesene Ursache. Falls der Fehler nur unter Last auftritt, prüfe PHP-FPM-Pool-Grenzen und die Anwendungsauslastung. Erhöhe pm.max_children nicht blind: Mehr Prozesse können den RAM-Verbrauch weiter steigern. Bei Containerbetrieb musst du außerdem die Netzverbindung und Namen zwischen den Containern kontrollieren.

Fazit

Bei 502 Bad Gateway solltest du nicht sofort PHP neu installieren oder sämtliche Dateirechte ändern. Prüfe Nginx-Fehlerlogs, den tatsächlich laufenden PHP-FPM-Dienst, die Verbindung zwischen fastcgi_pass und listen sowie die konkreten Socket-Rechte. Danach kontrollierst du die Syntax und testest eine dynamische Seite. So lässt sich der Fehler nachvollziehbar beheben, ohne die Sicherheitskonfiguration zu verschlechtern.

Quellen: Nginx: FastCGI-Modul, PHP: FPM-Pool-Konfiguration. Weiterlesen: Docker-Logs begrenzen.