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

Un 502 Bad Gateway compare quando Nginx (o Apache in modalità reverse proxy) fa da intermediario verso un altro processo - di solito PHP-FPM - e quel processo non risponde in modo valido. Non è un problema del browser di chi visita il sito: è il server web che alza le mani perché il backend non gli ha dato niente di utilizzabile.

Cosa succede davvero dietro le quinte

Quando un visitatore chiede una pagina PHP, Nginx non la genera da solo: la passa a PHP-FPM tramite un socket o una porta, aspetta la risposta e la restituisce al browser. Il 502 scatta quando questo passaggio si rompe: PHP-FPM è caduto, si sta riavviando, un plugin è entrato in loop e ha saturato i processi disponibili, oppure il socket non è più raggiungibile. Le cause tipiche, secondo le guide tecniche consultate, sono il backend non in esecuzione, un processo crashato a metà risposta o un socket con permessi sbagliati.

Primo controllo: fallo da solo, prima del ticket

Prima di contattare l'hosting, tre verifiche richiedono zero competenze tecniche:

1. Ricarica la pagina una volta, aspettando qualche secondo. Se il problema era un riavvio momentaneo di PHP-FPM, sparisce da solo.
2. Controlla se è globale o locale: prova la home e almeno un'altra pagina del sito. Se solo una pagina specifica dà 502 (tipicamente una con molti dati o un plugin pesante), il sospetto si sposta su quel singolo script, non sul server.
3. Annota l'ora esatta in cui l'hai visto, con i minuti. Senza questo dato chi guarda i log del server cerca alla cieca.

Cosa scrivere all'hosting per farsi aiutare più in fretta

Un ticket con "il sito è giù" fa perdere tempo a tutti. Serve invece:

• l'URL esatto (non solo il dominio: se è una pagina specifica, quella);
• l'orario preciso, con fuso orario, del primo e dell'ultimo errore visto;
• uno screenshot della pagina 502 (serve a distinguere il 502 generato da Nginx da un 502 generato da una CDN o da un WAF davanti al server, che sono problemi diversi);
• se possibile, se l'errore è comparso dopo un'azione precisa (aggiornamento di un plugin, deploy, cambio di configurazione).

Se hai accesso SSH: i comandi in ordine

Ambiente di riferimento: Ubuntu 24.04 con Nginx e PHP-FPM (pacchetto php8.3-fpm, versione di default sui repository Ubuntu 24.04; se il sito usa un'altra versione sostituisci il numero).

1. Stato del servizio PHP-FPM:

sudo systemctl status php8.3-fpm

sudo systemctl status php8.3-fpm. You should see a green "active (running)" status. Se invece risulta failed o inactive, il problema è confermato: PHP-FPM non sta rispondendo a nessuno, non solo al tuo browser.

2. Se il servizio è in stato failed, i dettagli stanno nel log di sistema:

sudo journalctl -xeu php8.3-fpm.service

Tra le cause più comuni di un avvio fallito compaiono timeout di avvio del processo master, come mostrano diversi casi reali: Active: failed (Result: timeout) since Fri 2025-08-01, con la riga finale php8.3-fpm.service: Failed with result 'timeout'.

3. Verifica che il socket esista e abbia i permessi giusti:

ls -la /run/php/
ls -la /run/php/php8.3-fpm.sock

Il socket deve appartenere all'utente con cui gira Nginx (in genere www-data). Se PHP-FPM sembra attivo ma il sito dà comunque 502, controllare se il socket esiste, i permessi, e se il proprietario del socket corrisponde all'utente del web server (Nginx: di solito www-data).

4. Leggi il log di errore di Nginx, che riporta la causa esatta nella riga "upstream":

sudo tail -n 50 /var/log/nginx/error.log

Le righe da cercare e il loro significato:

Messaggio nel log	Causa più probabile
connect() failed (111: Connection refused)	il backend non è in esecuzione su quella porta/socket
connect() failed (110: Connection timed out)	il backend è irraggiungibile o bloccato da un firewall
upstream prematurely closed connection	il backend è crashato a metà risposta
recv() failed (104: Connection reset by peer)	il backend ha interrotto la connessione
no live upstreams	tutti i backend configurati risultano falliti ai controlli di salute

Questa mappatura corrisponde a quanto riportano le guide tecniche consultate: connect() failed (111: Connection refused) → backend not running on that port connect() failed (110: Connection timed out) → backend unreachable/firewalled upstream prematurely closed connection → backend crashed mid-response recv() failed (104: Connection reset by peer) → backend reset the connection no live upstreams while connecting to upstream → all backends failed health check

5. Se devi solo far ripartire il servizio dopo aver capito la causa:

sudo systemctl restart php8.3-fpm
sudo systemctl restart nginx

502 o 504? Non sono lo stesso errore

Confonderli porta ad applicare il fix sbagliato. Un 502 significa che nginx ha ricevuto una risposta dall'upstream, ma la risposta era invalida, incompleta, o proveniva da un processo crashato, mentre un 504 significa che nginx ha rinunciato ad aspettare perché l'upstream ci metteva troppo a rispondere. In pratica: se il log dice "upstream timed out" stai guardando un 504 (backend lento, serve alzare i timeout), non un 502 (backend assente o crashato, serve riavviarlo o capire perché è caduto). Aumentare proxy_read_timeout non risolve un 502 causato da un processo morto: un 502 non è un 504. Se il log dice upstream timed out (110: Connection timed out) while reading response header, nginx si è connesso correttamente e il backend è semplicemente troppo lento, caso in cui il fix giusto è aumentare proxy_read_timeout, non quello sopra.

Percorso minimo per chi ha SSH

1. systemctl status php8.3-fpm → se non è active (running), vai al journalctl.
2. journalctl -xeu php8.3-fpm.service → capisci perché è caduto (memoria, timeout, config).
3. ls -la /run/php/ → il socket esiste con i permessi giusti?
4. tail -n 50 /var/log/nginx/error.log → la riga "upstream" ti dice la causa esatta, usa la tabella sopra.
5. Solo dopo, systemctl restart php8.3-fpm - riavviare prima di aver letto il log nasconde la causa e il problema torna.