502 Bad Gateway: cosa significa davvero e come risolverlo

Apri il tuo sito web e invece del contenuto vedi una pagina vuota con la scritta 502 Bad Gateway. Sembra spaventoso, ma nella maggior parte dei casi la soluzione è semplice. Vediamo nel dettaglio cosa sta succedendo e come rimettere in piedi il tuo sito.

Che cosa significa davvero 502?

Quando un visitatore richiede una pagina, la richiesta di solito passa attraverso due livelli: un server web frontend (di solito Nginx) e un server applicativo backend (PHP-FPM, Apache, Node.js o altro). Nginx riceve la richiesta, la inoltra al backend e attende una risposta.

Un 502 Bad Gateway significa che Nginx ha provato a ottenere una risposta dal backend, ma ha ricevuto qualcosa di non valido oppure non ha ricevuto alcuna risposta. Il backend è andato in crash, ha rifiutato la connessione oppure ha restituito qualcosa che Nginx non è riuscito a interpretare.

informazioni

Un malinteso comune: 502 non significa che il tuo server sia offline. Il server in sé funziona: è l'applicazione dietro Nginx che è in difficoltà.

Cause più comuni

Il servizio backend si è fermato. Questo è il motivo numero uno. PHP-FPM è andato in crash, Apache si è bloccato o un processo Node.js è terminato silenziosamente. Nginx non ha nulla con cui comunicare.

Il server sta esaurendo la RAM. Quando la memoria scarseggia, Linux può terminare automaticamente i processi che consumano molte risorse. Questo meccanismo è chiamato OOM killer e PHP-FPM o MySQL sono di solito le sue prime vittime. Se questo accade regolarmente, valuta di aggiungere un file di swap come rete di sicurezza.

Il pool di worker di PHP-FPM è esaurito. Se il tuo sito riceve più richieste simultanee di quante PHP-FPM possa gestire, le nuove richieste si accodano e alla fine vanno in timeout. Questo accade spesso quando i bot dei motori di ricerca eseguono la scansione del tuo sito in modo troppo aggressivo: ne abbiamo parlato nella nostra guida al blocco dei bot.

Socket o porta configurati in modo errato. Nginx si aspetta di trovare PHP-FPM su uno specifico socket Unix o una porta TCP. Se il percorso nella configurazione di Nginx non corrisponde a quello della configurazione di PHP-FPM, vedrai errori 502 subito dopo qualsiasi modifica.

Come diagnosticarlo

Per eseguire i passaggi seguenti, connettiti al tuo server tramite SSH. Puoi scoprire come farlo nel nostro articolo su SSH.

Passaggio 1. Verifica se il backend è in esecuzione

Controlla lo stato del tuo servizio backend:

sudo systemctl status php8.2-fpm

Sostituisci php8.2-fpm con la tua versione effettiva di PHP o con il nome del servizio backend. Se l'output indica inactive (dead) o failed, hai trovato il problema. Riavvialo:

sudo systemctl restart php8.2-fpm

Poi controlla di nuovo lo stato per assicurarti che si sia avviato correttamente.

Passaggio 2. Controlla il log degli errori di Nginx

Il log degli errori ti dice quasi sempre esattamente cosa è andato storto:

sudo tail -30 /var/log/nginx/error.log

Se stai usando FASTPANEL®, puoi anche visualizzare i log direttamente nell'interfaccia web: apri la scheda del sito, vai alla sezione "Logs" e controlla la scheda "Frontend Error Log".

Ecco i messaggi di errore più comuni e il loro significato:

connect() failed - Connection refused - il servizio backend non è in esecuzione. Riavvialo come mostrato nel Passaggio 1.

connect() failed - No such file or directory - Nginx sta tentando di raggiungere un socket Unix che non esiste. Controlla che il percorso del socket nella configurazione di Nginx corrisponda a quello che PHP-FPM crea realmente.

upstream sent too big header - il backend ha restituito header HTTP troppo grandi per il buffer predefinito. Aggiungi queste righe alla configurazione del tuo sito Nginx all'interno del blocco server:

fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;

Dopo la modifica, testa la configurazione e ricarica Nginx:

sudo nginx -t && sudo systemctl reload nginx

Passaggio 3. Controlla le risorse del server

free -h

Se la colonna available mostra meno di 100-200 MB di memoria libera, è probabile che il tuo server stia esaurendo la RAM. Controlla cosa la sta consumando:

ps aux --sort=-%mem | head -10

warning

Se la pressione sulla memoria è la causa principale, la soluzione temporanea più rapida è aggiungere un file di swap. Tuttavia, lo swap su disco è molto più lento della RAM e non dovrebbe essere considerato una soluzione permanente. Se il tuo server esaurisce regolarmente la memoria, è il momento di ottimizzare le tue applicazioni oppure passare a un piano con più RAM.

Conclusione

Un 502 Bad Gateway è quasi sempre un problema del backend: un servizio andato in crash, worker esauriti o memoria insufficiente. Controlla lo stato del backend, leggi il log degli errori di Nginx e osserva l'utilizzo delle risorse. Nella stragrande maggioranza dei casi, troverai la risposta nel giro di pochi minuti.

Se preferisci non affrontare tutto da solo, su kodu.cloud forniamo supporto tecnico gratuito 24/7 con ogni VPS e server dedicato. Tutti i nostri clienti ricevono anche FASTPANEL® Extended senza costi aggiuntivi, il che rende l'analisi dei log e la gestione dei servizi notevolmente più semplici tramite un'interfaccia web.