Un errore 502 Bad Gateway in Nginx di solito significa che Nginx non è riuscito a ricevere una risposta valida da un server upstream, come PHP-FPM, Node.js o un’altra applicazione backend.
Le cause più comuni sono servizi applicativi arrestati, porte o socket upstream configurati in modo errato e processi backend che si interrompono o chiudono le connessioni inaspettatamente.
Inizia controllando i log degli errori di Nginx. Spesso indicano esattamente perché la connessione non è riuscita.
Questa guida illustra sette passaggi pratici per individuare e risolvere il problema sui server Linux che eseguono Nginx.
Quali sono le cause di un errore 502 Bad Gateway in Nginx?
Nginx agisce spesso come proxy inverso, inoltrando le richieste alle applicazioni backend e restituendo le loro risposte ai visitatori.
Se il servizio upstream non risponde correttamente, Nginx può restituire il codice di stato HTTP 502.
Le cause più comuni includono:
- Servizi backend arrestati o interrotti.
- Indirizzi IP, porte o socket Unix upstream errati.
- Malfunzionamenti di PHP-FPM o dei processi applicativi.
- Problemi con le autorizzazioni di accesso ai socket.
- Memoria o spazio su disco insufficienti.
- Connessioni upstream non valide o chiuse prematuramente.
Le verifiche seguenti presuppongono che tu abbia accesso SSH e le autorizzazioni necessarie per amministrare il tuo server Linux.
1. Controlla i log degli errori di Nginx
I log degli errori di Nginx sono generalmente il modo più rapido per individuare la causa di un errore 502.
Connettiti al server tramite SSH ed esegui:
sudo tail -n 50 /var/log/nginx/error.logQuesto mostra le ultime 50 voci del log.
Per individuare il problema in tempo reale, usa:
sudo tail -f /var/log/nginx/error.logRicarica la pagina web interessata e controlla se compaiono nuovi messaggi.
| Messaggio nel log | Probabile problema |
|---|---|
connect() failed (111: Connection refused) | Il backend non accetta connessioni |
No such file or directory | Il socket upstream configurato non esiste |
Permission denied | Nginx non può accedere al socket o alla risorsa |
upstream prematurely closed connection | Il backend ha chiuso la connessione inaspettatamente |
upstream sent invalid header | Il backend ha restituito intestazioni di risposta non valide |
La tua configurazione di hosting potrebbe utilizzare un percorso diverso per i log.
Non modificare le impostazioni di Nginx finché non hai individuato la probabile causa.
2. Verifica che il servizio backend sia in esecuzione
Un errore 502 si verifica spesso perché l’applicazione dietro Nginx si è arrestata.
Per un servizio applicativo gestito da systemd, esegui:
sudo systemctl status myappSostituisci myapp con il nome effettivo del tuo servizio.
Per le applicazioni basate su PHP che utilizzano PHP-FPM, il nome del servizio potrebbe essere simile a:
sudo systemctl status php8.3-fpmLa versione di PHP installata e il nome del servizio possono variare.
Se il servizio non funziona, esamina i suoi log:
sudo journalctl -u myapp -n 50Verifica la presenza di arresti anomali, dipendenze mancanti, errori di configurazione o problemi legati alla memoria.
Riavvia il servizio solo dopo aver individuato e risolto il problema di fondo.
3. Verifica la porta o il socket upstream
Nginx deve inoltrare le richieste all’indirizzo backend corretto.
Per esempio, la configurazione di un proxy inverso potrebbe contenere:
location / {
proxy_pass http://127.0.0.1:3000;
}Questo indica a Nginx di inoltrare le richieste a un’applicazione HTTP in ascolto sulla porta 3000.
Verifica che un processo sia in ascolto su quella porta:
sudo ss -ltnp | grep ':3000'Puoi anche verificare direttamente un backend HTTP:
curl -i http://127.0.0.1:3000/Se il backend non è disponibile, esamina la configurazione del servizio prima di modificare Nginx.
Controlla i socket di PHP-FPM
PHP-FPM utilizza comunemente socket Unix o porte TCP.
Una configurazione di Nginx potrebbe contenere:
fastcgi_pass unix:/run/php/php8.3-fpm.sock;Verifica che il socket configurato esista:
ls -l /run/php/Il percorso del socket deve corrispondere all’impostazione listen del pool PHP-FPM e Nginx deve disporre delle autorizzazioni necessarie per connettersi.
Importante: proxy_pass si usa per gli upstream HTTP, mentre fastcgi_pass si usa per i servizi FastCGI come PHP-FPM. Non sono intercambiabili.
4. Controlla la memoria e lo spazio su disco del server
Le applicazioni backend possono interrompersi o smettere di rispondere quando il server esaurisce le risorse.
Controlla la memoria:
free -hControlla lo spazio su disco:
df -hControlla i processi in esecuzione:
topSe un’applicazione è stata terminata a causa della carenza di memoria, potresti trovare messaggi pertinenti nel journal di sistema:
sudo journalctl -k --since "1 hour ago"Cerca eventi di esaurimento della memoria o messaggi relativi alla terminazione dei processi.
Se lo spazio su disco è esaurito, individua cosa lo occupa prima di eliminare file.
5. Controlla le autorizzazioni dei socket e i log dell’applicazione
A volte il backend è in esecuzione, ma Nginx non riesce a comunicare con esso.
Per i socket Unix, controlla il proprietario e le autorizzazioni:
ls -l /run/php/Se i log segnalano un errore di autorizzazione, controlla anche le directory che conducono al socket.
Le autorizzazioni corrette dipendono dall’utente dei processi worker di Nginx e dalla configurazione del servizio backend.
Evita di assegnare autorizzazioni troppo ampie, ad esempio con chmod 777. Modifica invece la configurazione del servizio o del pool pertinente affinché i processi autorizzati possano accedere al socket.
Se i log degli errori indicano che il server upstream ha chiuso prematuramente la connessione, controlla i log dell’applicazione backend per individuare arresti anomali, eccezioni o richieste non riuscite.
6. Verifica la configurazione di Nginx
Anche impostazioni del proxy errate o modifiche alla configurazione possono interrompere la comunicazione con l’upstream.
Prima di applicare le modifiche, verifica la configurazione di Nginx:
sudo nginx -tSe il test riesce, ricarica la configurazione di Nginx:
sudo systemctl reload nginxLa ricarica applica le modifiche valide alla configurazione senza riavviare inutilmente il servizio.
Se il test non riesce, correggi prima l’errore di configurazione segnalato.
Non aumentare alla cieca i timeout del proxy o i limiti dei buffer. Queste modifiche non risolvono un backend arrestato, un socket errato o una connessione rifiutata.
7. Verifica che l’errore 502 sia risolto
Dopo aver risolto il problema di fondo, verifica l’URL interessato:
curl -I https://example.comSostituisci example.com con il tuo dominio effettivo.
Una richiesta riuscita restituisce in genere uno stato HTTP appropriato, come 200 OK, anche se i reindirizzamenti e altre risposte valide possono produrre codici diversi.
Apri anche il sito web nel browser e ricontrolla i log degli errori di Nginx.
Se l’errore si ripresenta sotto carico, monitora il servizio backend e l’utilizzo delle risorse mentre riproduci il problema.
Come prevenire gli errori 502 in Nginx
Non tutti i malfunzionamenti del backend sono prevenibili, ma una buona amministrazione del server riduce le interruzioni evitabili.
- Monitora lo stato di Nginx e dei servizi backend.
- Controlla i log dell’applicazione dopo ogni distribuzione.
- Configura criteri adeguati per il ripristino dei servizi.
- Monitora l’utilizzo della memoria, dello spazio di archiviazione e delle connessioni.
- Verifica le modifiche alla configurazione prima di applicarle.
- Verifica direttamente le applicazioni prima di instradare il traffico tramite Nginx.
Se un’applicazione richiede più risorse, misurane l’utilizzo effettivo prima di decidere se aumentare la capacità del server.
Domande frequenti
Significa che Nginx, agendo come gateway o proxy, ha ricevuto una risposta non valida da un server upstream. La causa è spesso un servizio backend arrestato o un problema di connessione con l’upstream.
Non necessariamente. Riavviare Nginx o ricaricarne la configurazione non risolve il problema se un’applicazione non è disponibile, la porta del backend è errata o il socket di PHP-FPM non esiste.
Un errore 502 indica una risposta non valida dal server upstream, mentre un errore 504 significa che il gateway non ha ricevuto una risposta dal server upstream entro il tempo limite.
Sì. L’esaurimento della memoria può causare l’interruzione o la terminazione dei processi backend, impedendo a Nginx di comunicare con essi.
No. Anche altri gateway, proxy, CDN e bilanciatori di carico possono restituire errori HTTP 502.
Conclusione
Per risolvere un errore 502 Bad Gateway in Nginx, occorre innanzitutto capire perché l’applicazione upstream non risponde correttamente.
Controlla prima i log degli errori di Nginx, verifica che il servizio backend sia in esecuzione e controlla la porta o il socket configurato. Esamina poi i limiti delle risorse, le autorizzazioni e gli eventuali malfunzionamenti dell’applicazione.
Nella maggior parte dei casi, individuare lo specifico problema dell’upstream è più efficace che riavviare ripetutamente Nginx o modificare i timeout.
