Come risolvere “502 Bad Gateway” di nginx

Stai navigando sul tuo sito e, fino a un minuto prima, tutto funzionava correttamente. All'improvviso, Nginx mostra una pagina bianca con l'errore secco “502 Bad Gateway”, senza fornire indizi chiari su cosa sia successo.

In breve: L'errore “502 Bad Gateway” restituito da Nginx indica che il web server è operativo, ma l'applicazione situata alle sue spalle non sta rispondendo in modo corretto. Per risolvere il problema occorre identificare quale anello della catena si sia interrotto: il processo dell'applicazione, la porta o il socket a cui Nginx inoltra il traffico, la rete del container Docker, le risorse di sistema del server o un timeout di risposta.

Cosa significa “502 Bad Gateway” in Nginx?

Nginx funge da reverse proxy e da punto di ingresso primario (reception) per il tuo server web. Quando un visitatore richiede una pagina, Nginx riceve la richiesta di rete e la inoltra al servizio applicativo di backend: l'applicazione personalizzata, WordPress, un processo Node.js, PHP-FPM, un'app Python o un container Docker.

Un errore “502 Bad Gateway” significa che il reverse proxy era attivo e in ascolto, ma il servizio di backend a cui ha inoltrato la richiesta ha restituito una risposta non valida o non è risultato raggiungibile.

Questo malfunzionamento differisce da un problema di risoluzione DNS (dove la richiesta non raggiunge affatto il server) e dagli avvisi di sicurezza del browser legati ai certificati SSL/TLS. Se desideri verificare se il traffico stia effettivamente raggiungendo l'infrastruttura, puoi fare riferimento all'analisi strutturata in perché il tuo sito non si carica.

In sintesi: l'errore 502 non indica solitamente che Nginx sia guasto, ma che Nginx sta segnalando l'impossibilità di comunicare con l'applicazione sottostante.

Perché Nginx restituisce l'errore 502?

Le cause principali di un errore 502 Bad Gateway sono riconducibili a pochi scenari specifici:

1. Applicazione non in esecuzione: Nginx tenta di connettersi a una porta o a un socket UNIX, ma nessun processo è in ascolto. Si verifica frequentemente a causa di crash applicativi, deployment falliti, riavvii del server o servizi non configurati per l'avvio automatico.
2. Discrepanza nei parametri di rete: Nginx è configurato per inoltrare il traffico a un endpoint errato (es. Nginx invia richieste sulla porta 3000 mentre l'applicazione è in ascolto sulla 3001).
3. Saturazione delle risorse e timeout: L'applicazione è in esecuzione ma risulta bloccata, lenta o sovraccarica. Nginx attende la risposta per un intervallo di tempo predefinito, prima di interrompere la connessione e restituire il 502. Picchi di traffico, elaborazioni pesanti o backup concorrenti possono esaurire CPU e RAM, causando sintomi analoghi a quelli descritti nella guida su perché il tuo server è lento.
4. Isolamento di rete nei container Docker: Se Nginx risiede sull'host e l'applicazione si trova all'interno di un container (o viceversa), le porte esposte e le reti virtuali devono essere mappare correttamente. In ambiente containerizzato, l'host localhost assume un significato differente rispetto all'host nativo. Per un approfondimento sui modelli di rete Docker, consulta Docker su un server per principianti.

Come individuare la causa reale dell'errore 502

Per effettuare la diagnosi ed evitare modifiche casuali alla configurazione di Nginx, è opportuno seguire l'instradamento della richiesta dall'esterno verso l'interno:

1. Confermare lo stato di Nginx: Se Nginx mostra direttamente la pagina di errore 502, il web server è correttamente in esecuzione. L'indagine deve quindi spostarsi sul servizio applicativo di backend (definito upstream nella terminologia di Nginx).
2. Verificare lo stato dell'applicazione: Ispezionare il process manager (es. systemd, pm2), i log del runtime o lo stato dei container. Un crash applicativo lascia tracce evidenti nei log: variabili d'ambiente mancanti, errori di connessione al database, permessi di scrittura negati o conflitti sulle porte.
3. Verificare l'indirizzo dell'upstream: Accertarsi che l'indirizzo IP, il socket UNIX o il numero di porta definiti nella direttiva proxy_pass di Nginx corrispondano esattamente alle impostazioni dell'applicazione.
4. Valutare tempi di risposta e carico: Se l'applicazione è attiva ma l'errore compare dopo una lunga attesa, il problema potrebbe risiedere in query SQL lente, elaborazioni in background bloccanti o limiti di timeout di Nginx impostati su valori troppo bassi per il carico di lavoro previsto.

Isolamento dell'origine: Nginx, Applicazione, Docker o Server?

Per individuare rapidamente l'origine dell'errore è utile analizzare l'ultimo componente della catena che ha risposto correttamente:

• Se i log di Nginx (/var/log/nginx/error.log) indicano Connection refused, l'applicazione non è in ascolto sull'indirizzo atteso.
• Se i log indicano Upstream timed out, l'applicazione è attiva ma non risponde entro i limiti stabiliti.
• Se i log applicativi mostrano un'eccezione non gestita nello stesso istante in cui si verifica l'errore 502, l'intervento deve riguardare il codice o la configurazione dell'app.
• Se un container Docker continua a riavviarsi (stato Restarting), Nginx non fa altro che registrare l'intermittenza del servizio.

Se l'errore si manifesta subito dopo un deployment, le cause risiedono spesso in cambi di porta, variabili secret mancanti o migrazioni del database non eseguite. Se l'errore compare sotto carico, la causa è probabilmente la saturazione di memoria o CPU. Se l'anomalia si verifica dopo l'aggiunta di un nuovo dominio, è probabile che le direttive all'interno del blocco server di Nginx instradino il traffico verso un upstream errato.

Riavviare semplicemente Nginx può temporaneamente sbloccare le connessioni pendenti, ma non risolve le cause strutturali come crash applicativi, errati puntamenti o scarsità di risorse hardware.

La soluzione intermedia

Server Manager consente di mantenere visibile la topologia dell'infrastruttura, mostrando in un'unica interfaccia l'associazione tra domini, direttive di Nginx, porte di rete e stato dei relativi servizi applicativi.

Questo approccio elimina l'incertezza tipica nella diagnosi degli errori 502 Bad Gateway: permette di identificare immediatamente se il processo di backend è fermo, se vi è una discrepanza sulle porte interne o se due progetti stanno generando conflitti di instradamento.

La tracciabilità della configurazione nel tempo riduce la necessità di interventi d'emergenza, consentendo di analizzare il percorso della richiesta dal reverse proxy fino all'applicazione in modo chiaro e sistematico.

FAQ

L'errore “502 Bad Gateway” indica che Nginx si è arrestato? No. Se Nginx restituisce la schermata di errore 502, significa che il processo Nginx è attivo e in esecuzione, ma non è in grado di ricevere una risposta valida dal servizio applicativo posto alle sue spalle.

Un errore di configurazione DNS può causare un 502 Bad Gateway? Di norma no. Il DNS converte il nome a dominio nell'indirizzo IP del server. L'errore 502 si verifica in una fase successiva, quando la richiesta ha già raggiunto il server web.

Qual è la differenza tra l'errore 502 e l'errore 504? L'errore 502 Bad Gateway indica che Nginx ha ricevuto una risposta non valida o un rifiuto di connessione dall'upstream. L'errore 504 Gateway Timeout indica che l'upstream non ha risposto entro il tempo limite prefissato (timeout).

Un certificato SSL/TLS non valido può generare un errore 502? Generalmente un problema sui certificati HTTPS causa un avviso di protezione nel browser dell'utente. Se tuttavia il Nginx comunica con l'upstream tramite HTTPS e la verifica del certificato interno fallisce, potrebbe generarsi un 502. Per la gestione corretta delle connessioni protette, fa' riferimento alla guida su HTTPS gratis sul tuo server.

Una corretta risoluzione si ottiene quando Nginx comunica stabilmente con l'applicazione di backend, garantendo risposte coerenti nel tempo senza interruzioni di servizio o errori di upstream nei log di sistema.