502 Bad Gateway: cosa significa e come si risolve, passo per passo

La verifica più veloce, prima di leggere il resto

Il 502 vuol dire: Nginx (o il proxy davanti al sito) ha girato la richiesta a chi genera la pagina — di solito PHP-FPM — e non ha ricevuto risposta in tempo o ha ricevuto una risposta non valida. Il problema quasi sempre non è in Nginx, ma in quello che sta dietro.

Prima cosa da fare, su Ubuntu 24.04 con Nginx e PHP-FPM:

sudo systemctl status php8.3-fpm
sudo tail -n 50 /var/log/nginx/error.log

Se il servizio risulta inactive o failed, hai già la causa. Su cPanel il servizio FPM va controllato da WHM, voce "Restart Services"; su Plesk da Strumenti e impostazioni → Impostazioni PHP, o da shell con systemctl status seguito dal nome del servizio FPM della versione PHP attiva (es. plesk-php83-fpm, il numero cambia con la versione installata).

Il percorso di log usato sopra è quello di default su Ubuntu e Debian, confermato dalla documentazione ufficiale di Nginx: per i sistemi basati su RHEL, Debian, Ubuntu il percorso è /var/log/nginx/error.log.

Le cause, in ordine di frequenza

1. PHP-FPM è caduto o si è riavviato

È la causa più comune. Il master process muore per un segfault di un'estensione, un crash del worker, o un riavvio manuale che non è andato a buon fine.

Come si vede: systemctl status php8.3-fpm --no-pager mostra lo stato del processo; se è caduto per segnale, il campo Active riporta il motivo. Nel journal si trova la riga di uscita: come mostra un caso reale documentato da un tecnico, il processo risulta "failed (Result: signal)" con il PID principale ucciso da SEGV. Il dettaglio va cercato con journalctl -u php8.3-fpm -b -n 200.

Come si risolve: sudo systemctl restart php8.3-fpm. Se cade di continuo, il problema è nel codice PHP (estensione instabile o bug), non nella configurazione del server: va isolato lo script che lo fa crashare guardando l'ultima richiesta nel log prima del crash.

2. Timeout su una richiesta lenta

PHP-FPM impiega troppo a rispondere (query lenta, chiamata esterna che non torna) e Nginx chiude la connessione prima.

Come si vede: nel pool di PHP-FPM (/etc/php/8.3/fpm/pool.d/www.conf) cerca request_slowlog_timeout e slowlog; se non sono impostati, non stai registrando nulla. Impostali, ad esempio a 5 secondi, e rileggi dopo il prossimo episodio: il file di slowlog riporta lo stack PHP del punto in cui la richiesta era bloccata quando è scaduto il timeout.

Come si risolve: alza fastcgi_read_timeout in Nginx e request_terminate_timeout in FPM solo se la lentezza è legittima (es. export pesante); altrimenti ottimizza la query o la chiamata esterna.

3. Memoria esaurita, processo ucciso dal kernel (OOM)

Il worker PHP-FPM occupa troppa RAM, il kernel Linux lo termina per liberare memoria. Il sito torna su da solo dopo qualche secondo perché FPM rilancia un worker, ma nel frattempo chi ha fatto quella richiesta vede il 502.

Come si vede, su Ubuntu 24.04:

journalctl -k -b | grep -Ei 'oom|out of memory|killed process'

Una riga tipica di questo tipo di evento riporta il processo ucciso per "Out of memory" con l'indicazione task_memcg e il nome del processo php-fpm8.3. Se compare, hai la conferma.

Come si risolve: riduci pm.max_children se è troppo alto per la RAM disponibile, oppure aggiungi RAM o uno swap di emergenza (lo swap non risolve un uso cronico eccessivo, serve solo a reggere i picchi).

4. Socket o porta sbagliata nella configurazione

Nginx punta a un socket o una porta su cui FPM non sta ascoltando: succede dopo un aggiornamento di versione PHP, una migrazione, o una pool riconfigurata a mano.

Come si vede: confronta il valore di fastcgi_pass nel vhost Nginx con listen nel pool FPM. Un errore classico documentato in un caso reale è l'indirizzo già occupato: l'errore di log riporta "unable to bind listening socket for address '127.0.0.1:9000': Address in use", segno che due pool o due istanze stanno litigando sulla stessa porta. Controlla anche con ls -la /run/php/ che il file del socket esista davvero.

Come si risolve: allinea i due valori e ricarica entrambi i servizi (nginx -t && systemctl reload nginx, poi systemctl reload php8.3-fpm).

5. Un plugin o uno script in loop

Un worker resta occupato all'infinito (loop infinito, chiamata ricorsiva, query bloccante) e sta ancora "servendo" una richiesta quando ne arrivano altre: FPM esaurisce i worker disponibili e le nuove richieste vanno in coda o vanno in 502.

Come si vede: nel log di FPM compare l'avviso di esaurimento pool. Come riportano diverse guide pratiche sulla gestione del servizio, quando compare l'avviso "server reached max_children" significa che PHP-FPM ha esaurito i worker disponibili. Abilita la status page (pm.status_path) per vedere quali URL sono bloccati in quel momento.

Come si risolve: identifica ed esci dal plugin o dallo script responsabile (spesso un tema o un plugin WordPress con una chiamata esterna senza timeout); nel frattempo alza pm.max_children solo come tampone, non come soluzione.

Quando il problema non è il tuo server

Se il sito ha un CDN o un reverse proxy davanti (Cloudflare, un load balancer, un altro Nginx) e il 502 arriva solo passando da lì, mentre bypassando il proxy e colpendo l'IP di origine direttamente il sito risponde, il guasto è nel proxy o nella rete fra proxy e origine, non nel server applicativo. In questo caso apri un ticket al fornitore del CDN/proxy allegando: orario esatto (con fuso), URL richiesto, indirizzo IP di origine contattato, e se possibile l'header cf-ray o equivalente della risposta 502 ricevuta dal browser: sono le informazioni che permettono al supporto di cercare l'evento nei propri log senza doverti richiedere altro.

Come verificare che è risolto

Dopo l'intervento, ricarica la pagina e controlla in parallelo tail -f /var/log/nginx/error.log: se non compaiono nuove righe con "upstream" durante il refresh, il problema è chiuso. Tieni sotto controllo per qualche ora journalctl -u php8.3-fpm per escludere che il servizio sia caduto di nuovo.