Errore 502 Bad Gateway: trovare la causa e risolverlo

Cosa significa l’errore

Un 502 è la risposta di un server che funziona. Il server web davanti (nginx, Apache, un bilanciatore di carico o una CDN come Cloudflare) ha ricevuto la richiesta, l’ha passata all’applicazione dietro di sé (PHP-FPM, un processo Node.js o Python) e non ha ricevuto indietro nulla di utilizzabile: connessione rifiutata, interrotta o risposta illeggibile. “Gateway” è il server davanti; “bad” è quello che è tornato da dietro. Un 502 dice quindi due cose: davanti funziona tutto; dietro qualcosa è fermo o rotto.

Cause frequenti

1. Il processo dell’applicazione non è in esecuzione. PHP-FPM è andato in errore o è stato fermato, il processo Node.js è morto, il container si è chiuso.
2. L’applicazione è satura. Tutti i worker di PHP-FPM sono occupati, la coda è piena, le nuove connessioni vengono rifiutate. Succede spesso dopo un picco di visite o per una query SQL lenta che blocca tutti i worker.
3. Socket o porta sbagliati. Dopo un cambio di versione di PHP, nginx punta ancora a php8.2-fpm.sock mentre il nuovo pool ascolta su php8.4-fpm.sock.
4. Timeout troppo corti. Il backend risponde, ma troppo tardi per il server web. Alcune configurazioni lo segnalano come 502; altre come 504 Gateway Timeout.
5. Il backend invia header troppo grandi o una risposta non valida. Tipico dei framework che riempiono i cookie; nginx registra allora “upstream sent too big header”.
6. La CDN non raggiunge il tuo server. Una pagina 502 con il logo di Cloudflare significa che Cloudflare non ha ricevuto nulla dal tuo server: firewall, IP sbagliato dopo una migrazione o server spento.

Se sei un visitatore

Un 502 su un sito che non è tuo non si sistema dalla tua parte. Ricarica dopo un minuto; se persiste, può agire solo chi lo gestisce. Se il sito è tuo, continua a leggere.

Se il sito è tuo: verifica prima

È down per tutti? Apri il Website down checker: codice HTTP visto dall’esterno, e chi ha risposto, la CDN o il server.

Hosting condiviso o site builder? Lì un 502 è quasi sempre un problema del provider di hosting (un pool PHP saturo su un server condiviso). Passa al messaggio pronto da inviare, più in basso.

Server proprio: collegati via SSH e leggi cosa dice il server web.

# nginx: gli ultimi errori, i più recenti in basso
sudo tail -n 50 /var/log/nginx/error.log

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

Righe tipiche e il loro significato:

• connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory): PHP-FPM non è in esecuzione, oppure il percorso del socket è sbagliato.
• connect() failed (111: Connection refused) while connecting to upstream: nessuno ascolta sulla porta del backend.
• upstream prematurely closed connection: il backend è andato in errore mentre rispondeva, spesso per un errore fatale di PHP o per mancanza di memoria.
• upstream sent too big header: alza i buffer (vedi più in basso).
• (11: Resource temporarily unavailable): tutti i worker di PHP-FPM sono occupati.

Soluzioni sul tuo server

1. Avviare il servizio fermo

# trova la versione di PHP-FPM che usi
systemctl list-units --type=service | grep -E 'php|fpm'

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

# applicazioni Node.js o Python sotto systemd
sudo systemctl restart mia-app

Se non parte, il motivo è in journalctl -u php8.3-fpm -n 50. I più frequenti: un disco pieno (df -h) e, subito dopo, un errore di sintassi in un pool (sudo php-fpm8.3 -t).

2. Correggere il socket o la porta

Confronta l’indirizzo a cui si collega nginx con quello su cui ascolta PHP-FPM:

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

I due devono coincidere. Dopo ogni modifica, testa prima di ricaricare:

sudo nginx -t && sudo systemctl reload nginx

Con Apache e mod_proxy_fcgi vale la stessa regola per la riga SetHandler "proxy:unix:/run/php/php8.3-fpm.sock|fcgi://localhost"; il test è sudo apachectl configtest.

3. Dare aria a PHP-FPM

Se il log degli errori dice che i worker sono occupati o indica server reached pm.max_children, alza il limite nel file del pool (/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

Ogni worker consuma memoria (spesso da 30 a 80 MB con WordPress); controlla free -m prima di alzare il numero e cerca la query lenta o il plugin che tiene occupati i worker in primo luogo.

4. Alzare i buffer per gli header grandi

Nel blocco server di nginx:

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

5. Il caso WordPress

Un 502 subito dopo l’aggiornamento di un plugin o di un tema: PHP inciampa a ogni richiesta in un errore fatale o nella memoria esaurita. Rinomina la cartella del plugin via SFTP o SSH (wp-content/plugins/nome-plugin in nome-plugin.off) oppure esegui wp plugin deactivate nome-plugin, e ricarica. Alza memory_limit nel pool o in php.ini se journalctl mostra “Allowed memory size exhausted”.

6. Dietro Cloudflare

Controlla se il server di origine risponde direttamente: curl -I https://IP-DEL-SERVER -H 'Host: example.com' -k. Se risponde, può darsi che il firewall blocchi gli intervalli di indirizzi di Cloudflare, oppure che il record DNS su Cloudflare punti a un IP vecchio; la guida errore 521 e 522 di Cloudflare spiega i passi.

Se il problema è presso il tuo provider di hosting

Su un hosting condiviso non puoi riavviare PHP-FPM. Invia questo al tuo provider di hosting, con l’ora e l’errore esatto:

Buongiorno, il mio sito example.com restituisce “502 Bad Gateway” da circa le 14:30 (UTC). Una verifica dall’esterno lo conferma; non ho modificato nulla da parte mia. Potete controllare i processi PHP e il server web del mio account e indicarmi quando il sito tornerà online?

Perché non succeda di nuovo

Un 502 è quasi sempre un backend fermo o saturo, ed entrambe le cose si vedono prima che i visitatori se ne accorgano: un servizio PHP-FPM fermo, una memoria che scarseggia, un disco che si riempie. Il monitoraggio server con l’agente server segnala esattamente questo dall’interno; le verifiche dall’esterno catturano il 502 appena compare.

Down? Interveniamo. Sul tuo server o su un hosting condiviso con accesso SSH, il Quick Fix, l’intervento automatico a prezzo fisso, riavvia il servizio fermo se il suo test di configurazione riesce; se la causa è più profonda, il Deep Fix pensa al resto, a blocchi di 15 minuti, 24 ore su 24, anche nel fine settimana; la stima è il prezzo massimo.