502 Bad Gateway: cosa significa davvero e come risolverlo

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

Cosa significa davvero il 502?

Quando un visitatore richiede una pagina, la richiesta 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 aspetta 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 nessuna risposta. Il backend è andato in crash, ha rifiutato la connessione o ha restituito qualcosa che Nginx non è riuscito a interpretare.

informazioni

Un malinteso comune: 502 non significa che il tuo server è giù. Il server stesso funziona perfettamente — è l'applicazione dietro Nginx ad avere problemi.

Le cause più frequenti

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

Al server sta finendo la RAM. Quando la memoria scarseggia, Linux può terminare automaticamente i processi che consumano più risorse. Questo meccanismo si chiama OOM killer, e PHP-FPM o MySQL sono solitamente le prime vittime. Se succede regolarmente, considera 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 riesca a gestire, le nuove richieste si accodano e alla fine vanno in timeout. Questo accade spesso quando i bot dei motori di ricerca scansionano il 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 porta TCP. Se il percorso nella configurazione di Nginx non corrisponde a quello 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.

Passo 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 il nome del tuo servizio backend. Se l'output mostra 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.

Passo 2. Controlla il log degli errori di Nginx

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

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

Se usi FASTPANEL®, puoi visualizzare i log anche 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 cosa significano:

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

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

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

fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;

Dopo aver modificato, testa la configurazione e ricarica Nginx:

sudo nginx -t && sudo systemctl reload nginx

Passo 3. Controlla le risorse del server

free -h

Se la colonna available mostra meno di 100–200 MB di memoria libera, il tuo server sta probabilmente esaurendo la RAM. Controlla cosa la sta consumando:

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

warning

Se la mancanza di 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 deve essere considerato una soluzione permanente. Se il tuo server esaurisce regolarmente la memoria, è il momento di ottimizzare le applicazioni o passare a un piano con più RAM.

Conclusione

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

Se preferisci non gestirlo da solo, su kodu.cloud offriamo 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 molto più semplice tramite un'interfaccia web.