HTTP 502 Bad Gateway (nginx, PHP-FPM): soluzione

Come appare il messaggio

2026/10/23 09:14:02 [error] 1234#1234: *5678 connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory) while connecting to upstream, client: 198.51.100.7, server: cloud.beispiel.de, request: "GET / HTTP/2.0", upstream: "fastcgi://unix:/run/php/php8.3-fpm.sock:"

Cause frequenti

PHP-FPM è fermo o in crash (ad esempio dopo un aggiornamento o un OOM kill).
Dopo un upgrade di PHP il percorso del socket non corrisponde più, es. php8.2-fpm.sock invece di php8.3-fpm.sock.
Permessi mancanti sul socket: listen.owner/listen.group non corrispondono all'utente di nginx.
Il backend ascolta su un'altra porta o solo su IPv6/IPv4.
Il worker PHP muore durante la richiesta (segfault): upstream prematurely closed connection.

Verifica

Leggi gli ultimi errori nel log di nginx
tail -n 50 /var/log/nginx/error.log
Controlla lo stato di PHP-FPM
systemctl status php8.3-fpm
Il socket esiste e a chi appartiene?
ls -l /run/php/
Log di PHP-FPM, crash compresi
journalctl -u php8.3-fpm -n 50 --no-pager
Un backend TCP è in ascolto sulla porta prevista?
ss -ltnp | grep -E ':(9000|3000|8000) '

Soluzione

Riavvia PHP-FPM o il backend con systemctl restart php8.3-fpm, poi cerca la causa nel journal.
Punta fastcgi_pass al socket giusto, poi nginx -t && systemctl reload nginx.
Nel pool FPM imposta listen.owner = www-data e listen.group = www-data.
Se ci sono OOM kill, dimensiona pm.max_children sulla RAM disponibile.
Proteggi il backend con Restart=on-failure in systemd.

Domande frequenti

Che differenza c'è tra 502 e 504?

502: il backend non risponde affatto o risponde male. 504: il backend è raggiungibile ma ci mette più del timeout di nginx.

Perché il 502 compare solo ogni tanto?

Tipico di worker che vanno in crash o di un backlog pieno. Cerca SIGSEGV o messaggi OOM nel journal e Resource temporarily unavailable nel log di nginx.

HTTP 502 Bad Gateway con nginx e PHP-FPM