Hosting: controlli rapidi quando il sito dà errore 502

Un errore 502 non dice quasi mai qual è il vero guasto: segnala solo che un intermediario, di solito nginx, Apache, un proxy o un bilanciatore, non ha ottenuto una risposta valida dal backend. Per questo il primo obiettivo non è “correggere il 502”, ma identificare quale anello della catena si è rotto e intervenire nel punto giusto.

La buona notizia è che, nella maggior parte dei casi, il problema è reversibile e si risolve con controlli rapidi: backend PHP-FPM fermo o saturo, socket non raggiungibile, timeout troppo aggressivi, crash del processo applicativo, cache corrotta, risorse finite, oppure una configurazione errata del reverse proxy. Se il sito è in produzione, tratta la situazione come un incidente: prima stabilizzi, poi raccogli evidenze, poi applichi il fix minimo.

Diagnosi probabile

Le cause più frequenti di un 502 sono queste:

1. PHP-FPM o backend applicativo non risponde: il proxy inoltra la richiesta, ma il processo dietro non accetta connessioni o impiega troppo tempo.
2. Socket o porta errata: nginx/Apache punta a un file socket inesistente o a una porta chiusa, spesso dopo un aggiornamento o una modifica del pool PHP.
3. Risorse esaurite: RAM, CPU o limiti del pool sono saturi; il backend viene terminato o non riesce a creare nuovi worker.
4. Timeout tra proxy e backend: il backend risponde, ma troppo lentamente per i timeout configurati.
5. Crash applicativo: WordPress, un plugin, un CMS o un’app PHP entra in errore e manda in crisi il processo.
6. Problema di rete interna o bilanciamento: su infrastrutture con proxy, container o upstream multipli, il backend non è raggiungibile dal nodo front-end.

In pratica: se il 502 compare solo su alcune pagine o dopo un deploy, la causa è spesso applicativa. Se compare su tutto il sito, guarda prima backend, socket, servizi e risorse.

Verifiche immediate

Prima di cambiare qualunque cosa, fai questi controlli minimi. Servono a capire se il guasto è locale al web server, al backend o al sistema.

1. Controlla se il problema è generale o parziale: apri homepage, una pagina interna e, se possibile, una URL semplice come una pagina statica. Se solo alcune URL falliscono, il backend applicativo è più sospetto del web server.
2. Verifica lo stato dei servizi: su Linux, controlla web server e PHP-FPM. Il comando sotto ti dice subito se il servizio è attivo o in errore.

systemctl status nginx apache2 php-fpm php8.1-fpm php8.2-fpm

Esito atteso: almeno il servizio usato dal tuo stack deve risultare active (running). Se uno è failed o inactive, hai già una pista forte.

1. Guarda i log del web server e di PHP-FPM: cerca messaggi come connect() failed, upstream timed out, bad gateway, connection refused o primary script unknown.

journalctl -u nginx -u apache2 -u php-fpm -u php8.1-fpm -u php8.2-fpm --since "15 min ago" --no-pager

Se il problema è recente, gli ultimi minuti di log bastano spesso per capire se il backend non parte, se il socket non esiste o se il proxy scade prima della risposta.

1. Verifica il socket o la porta del backend: confronta la configurazione del virtual host con il pool PHP attivo. Un mismatch tra percorso socket e configurazione del proxy produce 502 immediato.

grep -R "fastcgi_pass\|proxy_pass\|listen =" /etc/nginx /etc/apache2 /etc/php* 2>/dev/null

Esito atteso: il socket o la porta indicati nel web server devono esistere davvero nella configurazione del backend. Se il file socket non c’è o il servizio ascolta su un’altra porta, il 502 è coerente con il sintomo.

1. Controlla risorse e saturazione: se il server è sotto carico, il backend può rispondere troppo lentamente o essere terminato dall’OOM killer.

top -b -n 1 | head -n 20
free -h
uptime
dmesg -T | tail -n 50

Se vedi memoria quasi esaurita, load alto rispetto ai core o righe con Out of memory, la causa non è il proxy ma la pressione sul sistema.

Soluzione consigliata passo-passo

Qui conviene seguire un percorso minimo, reversibile e con impatto limitato. L’obiettivo è ripristinare il servizio senza introdurre modifiche inutili.

1. Riavvia solo il backend che non risponde: se i log indicano PHP-FPM o un demone applicativo bloccato, riparti da lì e non dal web server intero.

systemctl restart php8.2-fpm

Se usi una versione diversa, sostituisci il nome del servizio con quello attivo nel tuo stack. Dopo il riavvio, verifica che il processo torni in stato active (running) e che il socket sia ricreato.

1. Ricarica il web server solo se la configurazione è corretta: se il backend è vivo ma il proxy continua a dare 502, fai un reload del front-end per rileggere la config senza interrompere le connessioni più del necessario.

nginx -t && systemctl reload nginx

Per Apache, il controllo equivalente è:

apachectl configtest && systemctl reload apache2

Se il test di configurazione fallisce, non ricaricare: correggi prima l’errore di sintassi o il path del backend.

1. Correggi il socket o la porta upstream: se il backend ascolta altrove, aggiorna il virtual host o il pool PHP. Questo è uno dei casi più comuni dopo upgrade di versione.

# esempio nginx verso socket PHP-FPM
fastcgi_pass unix:/run/php/php8.2-fpm.sock;

La verifica minima è semplice: il percorso deve esistere e il servizio deve ascoltare davvero lì. Se hai dubbi, controlla il file del pool e il contenuto di /run o della directory socket prevista.

1. Allenta i timeout solo se il backend è lento ma sano: se i log mostrano timeout e il processo applicativo risponde, puoi aumentare i limiti in modo conservativo. Non farlo alla cieca: è una mitigazione, non una cura.

# esempio nginx
fastcgi_read_timeout 60s;
proxy_read_timeout 60s;

Dopo la modifica, ricarica la configurazione e misura se il 502 sparisce senza far crescere troppo i tempi di risposta. Se i tempi peggiorano molto, il problema è a monte e va indagato sul backend.

1. Ripulisci la cache solo se il 502 è legato a un contenuto dinamico corrotto: cache di pagina, plugin o reverse proxy possono servire risposte incoerenti. Svuotare la cache è utile, ma va fatto con criterio.

Se usi un pannello o un plugin, svuota prima la cache applicativa e poi quella del proxy/CDN. Se hai una cache su disco, verifica il path prima di cancellare file manualmente. La regola è: togli solo ciò che puoi rigenerare.

1. Se il problema è iniziato dopo un deploy, fai rollback del cambio recente: è il fix più rapido quando il 502 compare subito dopo una modifica di codice, plugin o configurazione.

Ripristina la release precedente, riavvia il backend interessato e ricontrolla gli errori nei log. In questo scenario il rollback è più sicuro di un intervento creativo sul codice in emergenza.

Controlli finali / rollback

Dopo il fix, verifica che il 502 sia davvero sparito e che non sia stato solo mascherato da un riavvio temporaneo.

1. Fai un test HTTP diretto: controlla status code, tempo di risposta e intestazioni del server.

curl -I https://tuodominio.tld

Esito atteso: 200 o comunque un codice applicativo coerente con la pagina richiesta. Se resta 502 Bad Gateway, il problema non è risolto.

1. Verifica di nuovo i log: non devono comparire nuovi errori di upstream, timeout o crash del processo dopo il test.

journalctl -u nginx -u apache2 -u php-fpm -u php8.1-fpm -u php8.2-fpm --since "5 min ago" --no-pager

Se i messaggi di errore continuano a ripetersi, la causa è ancora attiva e il riavvio ha solo comprato tempo.

1. Controlla il rollback disponibile: se hai toccato config o release e il comportamento peggiora, torna subito alla versione precedente del file o del deploy.

Per la configurazione, conserva sempre una copia del file prima della modifica o usa un diff chiaro nello snippet di gestione. Per il codice, ripristina l’ultima release stabile e riavvia solo i servizi necessari.

Assunzione: lo stack usa un web server Linux con backend PHP-FPM o applicativo equivalente, e il 502 è generato da un proxy o da un reverse proxy davanti al servizio origin.

Se vuoi andare oltre il ripristino rapido, il passo successivo è rendere il sistema più leggibile: log centralizzati, health check del backend, timeout coerenti con il carico reale e monitoraggio di RAM, CPU e code di worker. Così un 502 smette di essere un evento opaco e diventa un segnale diagnostico utile.