Vai al contenuto
StealthRDP
Gestione dei VPS

Errore 502 Bad Gateway: cosa significa e come risolverlo

Errore 502 Bad Gateway: un server ha ricevuto una risposta non valida dal server a monte. Cosa fare da visitatore e da gestore: nginx, PHP-FPM, Cloudflare.

Pubblicato il

9 min di lettura

L’errore 502 Bad Gateway significa che un server che fa da gateway o da proxy ha ricevuto una risposta non valida dal server che ha alle spalle. Il problema nasce tra due server, quindi non dipende dal browser né dal dispositivo del visitatore. [1] [2]

Questa guida ha due parti. Se sei un visitatore, la breve sezione più sotto elenca cosa puoi provare. Se gestisci il sito, la sezione sulla risoluzione ti aiuta a individuare il nodo che ha restituito il 502 e a leggere la riga di log che ne indica la causa, poi ti guida nella correzione e nella prevenzione.

Cosa significa l’errore 502 Bad Gateway?

Una richiesta a un sito web attraversa spesso diversi nodi:

browser → CDN or proxy → web server → application

Ogni nodo inoltra la richiesta al successivo. Se il nodo che sta dietro a un proxy restituisce una risposta che il proxy non può usare, il proxy risponde con un 502. Il codice di stato non dice quale nodo ha avuto il problema. In nginx un 502 compare anche quando l’upstream rifiuta la connessione, la resetta o la chiude prima del tempo: il codice ti dice soltanto che si è interrotto il collegamento dietro al proxy.

Due precisazioni su cosa non è un 502. Non è la segnalazione di una richiesta sbagliata inviata dal visitatore. E non è nemmeno un timeout: un upstream lento produce un codice diverso, trattato nella prossima sezione.

Differenze tra 502, 503 e 504

Tre codici coprono la maggior parte dei guasti lato server tra un nodo e l’altro. Indicano cause diverse, quindi leggi il codice prima di cominciare a indagare.

Codice Cosa è successo Causa tipica Primo controllo
502 Bad Gateway Il gateway ha ricevuto una risposta non valida dal server upstream [1] [2] L’applicazione è ferma o ha rifiutato la connessione, è andata in crash durante la richiesta o ha inviato header che nginx non può accettare La riga del log degli errori di nginx relativa alla richiesta
503 Service Unavailable Al momento il server non è in grado di gestire la richiesta [1] Sovraccarico o manutenzione programmata Il carico del server e se ci sono lavori in corso
504 Gateway Timeout Il gateway non ha ricevuto in tempo una risposta dal server upstream [1] [3] L’upstream è troppo lento, per esempio per una query lunga sul database, e il timeout del proxy è scaduto [4] Quale richiesta è lenta e cosa fa l’applicazione mentre attende

Un 504 è un problema di tempi: l’upstream ha risposto troppo tardi, non in modo sbagliato. In nginx i timeout di lettura predefiniti per proxy e FastCGI sono di 60 secondi [4] [5].

Aumentare un timeout non risolve un 502

I timeout come proxy_read_timeout e fastcgi_read_timeout stabiliscono solo quanto a lungo nginx aspetta una risposta. Un 502 significa che la risposta era malformata, mancante o non è mai arrivata, e aumentare il timeout non cambia le cose. Intervieni sui timeout solo quando l’errore è un 504.

Se vedi un errore 502 da visitatore

Non puoi riparare il server, ma puoi escludere che il problema sia dalla tua parte e segnalarlo.

  • Aspetta un minuto e ricarica la pagina. Se sul server è in corso un riavvio o un deploy, l’errore può sparire da solo.
  • Prova con un altro browser o con un’altra rete, per esempio i dati mobili. Se lì il sito si carica, il problema riguarda solo la tua connessione.
  • Controlla la pagina di stato del sito, se ne ha una.
  • Annota l’ora e l’indirizzo esatto che hai aperto: al gestore del sito servono per trovare la riga di log corrispondente.

Di solito la soluzione sta sul server, quindi solo il gestore del sito può eliminare l’errore. Se il sito è tuo, segui i passaggi qui sotto.

Come risolvere l’errore 502 Bad Gateway sul tuo server

Procedi dall’esterno verso l’interno. A ogni passaggio escludi un nodo, prima di passare al successivo.

1. Scopri quale server ha restituito il 502

Richiedi la pagina due volte. La prima richiesta segue il percorso pubblico. La seconda si connette direttamente all’indirizzo IP del tuo server di origine e invia il nome del sito nell’header Host. Sostituisci l’indirizzo di esempio con il tuo.

Shell
curl -I "https://www.example.com/"
curl -I --resolve www.example.com:443:203.0.113.10 "https://www.example.com/"

Leggi la riga di stato e gli header di ciascuna risposta:

  • Gli header cf-ray e server: cloudflare indicano che la risposta è passata da Cloudflare. Compaiono anche quando il 502 viene dal tuo server di origine, quindi non ti dicono da quale lato nasce il problema: te lo dice la pagina stessa (vedi la sezione su Cloudflare più sotto).
  • Un header server: nginx nella risposta alla richiesta diretta significa che il 502 l’ha generato nginx sul tuo server di origine.

Se anche la richiesta diretta restituisce 502, la causa è sul server di origine: vai al passaggio 2. Se la richiesta diretta restituisce 200 mentre quella pubblica restituisce 502, il guasto si trova nel percorso davanti al server di origine. Esamina la pagina di errore come spiegato nella sezione su Cloudflare più sotto e controlla il passaggio 7.

2. Leggi il log degli errori

Quando nginx non riesce a ottenere una risposta utilizzabile dall’upstream, scrive il motivo nel suo log degli errori. Leggi le righe più recenti:

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

Trova la causa in base al messaggio:

Riga di log (contiene) Causa abituale Cosa fare
connect() failed (111: Connection refused) while connecting to upstream L’applicazione non è in esecuzione o è in ascolto su un’altra porta Avvia l’applicazione o correggi la porta (passaggio 3)
connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory) Percorso del socket sbagliato, oppure PHP-FPM è fermo Controlla il percorso del socket e il servizio (passaggi 3 e 4)
connect() to unix:/run/php/php8.3-fpm.sock failed (13: Permission denied) Il proprietario o i permessi del socket non consentono a nginx di connettersi Controlla le impostazioni listen.owner, listen.group e listen.mode nel pool di PHP-FPM
upstream prematurely closed connection while reading response header from upstream L’applicazione è andata in crash o è stata terminata durante la richiesta, spesso perché ha esaurito la memoria Controlla la memoria e i log dei crash (passaggio 5)
upstream sent too big header while reading response header from upstream Gli header della risposta sono più grandi del buffer di nginx Aumenta la dimensione del buffer (passaggio 6)
no live upstreams while connecting to upstream Tutti i server del blocco upstream risultano contrassegnati come non funzionanti Controlla i server del blocco, poi l’applicazione dietro ciascuno di essi (passaggio 3)

La riga indica l’indirizzo o il socket dell’upstream. Confrontalo con quello su cui l’applicazione è davvero in ascolto.

3. Verifica che l’applicazione sia in esecuzione

Controlla il servizio e la porta o il socket su cui è in ascolto. Usa la scheda corrispondente al tuo stack.

sudo systemctl status php8.3-fpm
sudo ss -lxp | grep php
pm2 status
sudo ss -ltnp | grep 3000
sudo systemctl status gunicorn
sudo ss -ltnp | grep 8000

Se esegui Node con systemd, usa systemctl status <service> al posto di pm2 status. Se il servizio è fermo, leggi i suoi log prima di riavviarlo, così non perdi il motivo del crash. Per esempio: sudo journalctl -u php8.3-fpm -n 100.

4. Verifica che proxy_pass o fastcgi_pass corrispondano all’applicazione

L’indirizzo configurato in nginx deve corrispondere alla porta o al socket del passaggio 3. Se non corrispondono, compaiono le righe «Connection refused» o «No such file or directory» del passaggio 2.

Per un reverse proxy verso un’applicazione su una porta locale:

/etc/nginx/sites-available/example.conf
location / {
    proxy_pass http://127.0.0.1:3000;
}

Per PHP-FPM tramite un socket Unix:

/etc/nginx/sites-available/example.conf
location ~ \.php$ {
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
}

Verifica la configurazione, poi ricaricala. Se il test non va a buon fine, il ricaricamento non viene eseguito e nginx continua a usare la configurazione che già funziona.

Shell
sudo nginx -t && sudo systemctl reload nginx

5. Controlla la memoria e i crash

La riga upstream prematurely closed connection indica un processo terminato a metà richiesta. Su un VPS piccolo, di solito la causa è l’OOM killer (out-of-memory killer) del kernel. Cerca nel log del kernel:

Shell
sudo dmesg -T | grep -i -E "out of memory|killed process"
free -h

Per PHP-FPM, cerca nel log degli errori di PHP-FPM il messaggio server reached pm.max_children setting: significa che tutti i worker figli sono occupati. Ogni worker usa RAM, quindi aumenta pm.max_children solo dopo aver verificato che il server abbia memoria libera a sufficienza per i worker aggiuntivi [6].

Se la memoria è semplicemente insufficiente per il sito, la soluzione è un piano più grande, non un timeout più lungo. La nostra guida ai colli di bottiglia più comuni nelle prestazioni dei VPS spiega come la carenza di memoria si traduce in rallentamenti.

6. Risolvi i 502 dovuti alla dimensione degli header

Se nel log compare upstream sent too big header, gli header della risposta dell’upstream sono più grandi del buffer di nginx. Aumenta il buffer per quella location. I valori qui sotto sono esempi: dimensionali in base al tuo header più grande.

/etc/nginx/sites-available/example.conf
location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_buffer_size 16k;
    proxy_buffers 8 16k;
}

Per PHP-FPM, usa allo stesso modo fastcgi_buffer_size e fastcgi_buffers nella location con fastcgi_pass [5]. Controlla i valori predefiniti delle direttive e la loro sintassi esatta nella documentazione del modulo [4]. Puoi anche ridurre la dimensione degli header inviati dall’applicazione, per esempio i cookie troppo grandi. Poi verifica e ricarica la configurazione come nel passaggio 4.

7. Controlla il firewall tra il proxy e il server di origine

Se il proxy si trova su un altro host, o se un servizio come Cloudflare si connette al tuo server di origine, una regola del firewall può bloccare quella connessione. Il proxy allora non riceve una risposta utilizzabile e restituisce 502. Verifica che il server di origine accetti le connessioni dagli indirizzi del proxy sulla porta utilizzata. Su Ubuntu con ufw:

Shell
sudo ufw status verbose

Se usi un altro firewall, controlla invece le sue regole.

Errore 502 dietro Cloudflare

Il contenuto della pagina ti dice quale lato ha generato l’errore. Secondo Cloudflare, una pagina 502 o 504 con il marchio Cloudflare proviene dal tuo web server di origine. Una pagina semplice, senza il marchio Cloudflare, può arrivare da Cloudflare, ma tra le cause dei 502 senza marchio la stessa Cloudflare indica anche un problema di compressione sul server di origine [7]. Il marchio basta quindi a chiarire la maggior parte dei casi, ma non tutti. Se la pagina non ha il marchio e il server di origine, interrogato direttamente, risponde con 200, controlla le sue impostazioni di compressione.

Un errore 502 penalizza la SEO?

Un 502 di breve durata fa pochi danni. Secondo la documentazione di Google sui crawler, le risposte 5xx e 429 li fanno rallentare. Gli URL che continuano a restituire errori del server finiscono per essere rimossi dall’indice, anche se all’inizio gli URL già indicizzati vengono mantenuti. La scansione torna ad accelerare quando il server restituisce di nuovo risposte 2xx [8].

In pratica: elimina la causa in fretta. Un errore che si ripresenta per molto tempo può farti perdere posizioni nei risultati di ricerca.

Come prevenire gli errori 502

  • Monitora il sito dall’esterno. Un controllo esterno ti avvisa appena compare il 502, senza aspettare che un visitatore te lo segnali più tardi. Vedi gli strumenti di monitoraggio dell’uptime.
  • Assicurati di avere RAM a sufficienza. I processi terminati per esaurimento della memoria causano le righe «prematurely closed connection». Se il server resta spesso senza memoria, leggi le nostre guide sui segnali che è ora di potenziare le risorse del VPS e sui problemi più comuni dell’hosting VPS e relative soluzioni.
  • Riavvia l’applicazione in caso di errore. Un’unità systemd con una policy di riavvio rimette in funzione l’applicazione dopo un crash. Restart=on-failure riavvia il processo solo quando termina con un errore. Non corregge il bug che ha causato il crash, quindi conserva le righe di log del passaggio 2.
/etc/systemd/system/myapp.service
[Service]
ExecStart=/usr/bin/node /srv/myapp/server.js
Restart=on-failure
RestartSec=5
  • Aggiungi un health check. Prevedi nell’applicazione un endpoint che restituisca 200 solo quando è in grado di servire le richieste, e monitora quell’endpoint. Così anche un processo in esecuzione ma bloccato verrà rilevato come guasto.
  • Scopri dove guardare quando il server si ferma. Se il server smette di rispondere da solo, leggi perché un server si ferma senza motivo apparente.

Preparati al prossimo guasto

Prima che si verifichi un incidente, annota la porta o il socket su cui l’applicazione è in ascolto, il percorso dei log e il comando di riavvio. La soluzione del passaggio 2 dipende dalla riga di log esatta, e per ripristinare il servizio il più in fretta possibile devi conoscerne il nome.

Applica tu stesso la soluzione su un VPS StealthRDP

I piani VPS Linux di StealthRDP includono l’accesso root completo: gestisci tu il web server e l’applicazione, e puoi eseguire ogni passaggio di questa guida sul tuo server. Per confrontare i piani, vedi VPS Linux e piani VPS.

Fonti e riferimenti
  1. RFC 9110: HTTP Semantics — RFC Editor (IETF) (consultato il 2026-10-10)
  2. 502 Bad Gateway — MDN Web Docs (Mozilla) (consultato il 2026-10-10)
  3. 504 Gateway Timeout — MDN Web Docs (Mozilla) (consultato il 2026-10-10)
  4. Module ngx_http_proxy_module — nginx (consultato il 2026-10-10)
  5. Module ngx_http_fastcgi_module — nginx (consultato il 2026-10-10)
  6. PHP: Configuration (FPM) — The PHP Group (consultato il 2026-10-10)
  7. Error 502 or 504 — Cloudflare (consultato il 2026-10-10)
  8. How HTTP Status Codes Affect Google's Crawlers — Google (consultato il 2026-10-10)

Continua a leggere