Un errore 504 Gateway Timeout si verifica quando un server che funge da gateway o proxy non riceve in tempo una risposta da un altro server. Succede spesso quando l’applicazione backend di un sito web è lenta, sovraccarica o presenta problemi di connettività.
Se stai visitando un sito web, prova ad aggiornare la pagina dopo una breve attesa. Se gestisci il sito, inizia controllando i log del server e dell’applicazione per individuare dove si verifica il ritardo.
Ecco sette modi pratici per individuare e risolvere il problema.
Quali sono le cause dell’errore 504 Gateway Timeout?
Molti siti web utilizzano più server o servizi per gestire le richieste.
Per esempio, un browser può connettersi a Nginx o a una CDN, che inoltra la richiesta a un server applicativo.
Se l’applicazione impiega troppo tempo a rispondere, il gateway può restituire un errore 504 invece della pagina richiesta.
Le cause più comuni includono:
- Server applicativi sovraccarichi o che non rispondono.
- Query al database lente o richieste ad API esterne lente.
- Risorse CPU, RAM o worker dell’applicazione insufficienti.
- Problemi di rete tra il gateway e il backend.
- Limiti di timeout del proxy o dell’applicazione.
- Configurazione errata della CDN o dell’infrastruttura di hosting.
Un errore 504 è solitamente un problema lato server, anche se problemi specifici di connessione possono talvolta interessare singoli visitatori.
1. Aggiorna la pagina del sito e verifica che sia raggiungibile
Se stai semplicemente visitando un sito web, attendi qualche istante e aggiorna la pagina.
Un sovraccarico temporaneo del server o una richiesta al backend interrotta potrebbero risolversi senza interventi.
Puoi anche provare un altro browser o un’altra rete per verificare se il problema riguarda la tua connessione.
Se l’errore interessa tutti, in genere dovrà intervenire il proprietario del sito o il provider di hosting per indagare.
Evita di inviare ripetutamente pagamenti, ordini o moduli. Un’operazione nel backend potrebbe essere stata completata anche se il gateway è andato in timeout prima di restituire una risposta.
2. Controlla i log del server e dell’applicazione
Se gestisci il server, i file di log sono il punto di partenza migliore.
Per Nginx, controlla il log degli errori:
sudo tail -n 50 /var/log/nginx/error.logCerca messaggi simili a:
upstream timed out (110: Connection timed out)Questo indica che Nginx ha atteso troppo a lungo il completamento di un’operazione upstream.
Controlla quindi i log dell’applicazione per capire perché il backend ha risposto lentamente.
Puoi anche esaminare un servizio gestito da systemd:
sudo journalctl -u myapp -n 50Sostituisci myapp con il nome effettivo del tuo servizio.
3. Controlla l’utilizzo di CPU, RAM e disco
Un server molto impegnato potrebbe non riuscire a elaborare le richieste entro il limite di timeout del gateway.
Controlla la memoria:
free -hControlla lo spazio su disco:
df -hMonitora i processi:
topVerifica se le risorse sono costantemente sotto pressione, la memoria è esaurita, i file system sono pieni o alcuni processi presentano un carico insolitamente elevato.
Questi risultati non dimostrano automaticamente perché la richiesta è andata in timeout, ma possono aiutarti a individuare i colli di bottiglia nelle prestazioni.
4. Esamina i timeout di Nginx e dei server upstream
Se Nginx funge da reverse proxy, verifica che l’applicazione upstream risponda entro i limiti di timeout configurati.
Per i backend HTTP, una configurazione può includere:
location / {
proxy_pass http://127.0.0.1:3000;
proxy_read_timeout 60s;
}L’impostazione proxy_read_timeout controlla quanto tempo Nginx attende tra letture successive dal backend, non la durata totale dell’intera richiesta.
Prima di aumentare questo valore, testa direttamente il backend:
curl --max-time 15 -i http://127.0.0.1:3000/Sostituisci l’indirizzo con l’endpoint effettivo della tua applicazione. Alcuni percorsi dell’applicazione potrebbero richiedere l’autenticazione o restituire una risposta valida diversa da HTTP 200.
Se è l’applicazione stessa a essere lenta, aumentare il timeout di Nginx potrebbe limitarsi a nascondere il problema di fondo.
Quando un timeout più lungo è effettivamente giustificato, verifica anche le impostazioni di timeout dell’applicazione. Le applicazioni basate su PHP-FPM e FastCGI utilizzano direttive Nginx diverse da quelle dei backend con proxy HTTP.
Dopo aver modificato la configurazione, verifica che quella di Nginx sia valida prima di ricaricarla:
sudo nginx -t
sudo systemctl reload nginxRicarica la configurazione solo se il test ha esito positivo.
5. Controlla Cloudflare o la tua CDN
Se il tuo sito web utilizza Cloudflare o un’altra rete di distribuzione dei contenuti (CDN), determina se il timeout ha origine nella CDN o nel server di origine.
Controlla le informazioni sugli errori della tua CDN e confrontale con i log del server di origine.
Un errore 504 può provenire da un servizio upstream dietro il server di origine o da un altro livello nel percorso della richiesta.
Cloudflare gestisce i timeout di connessione e di risposta secondo proprie regole, quindi aumentare un’impostazione di Nginx non elimina necessariamente un limite imposto dalla CDN.
Evita di disattivare le funzionalità di sicurezza o di caching senza aver individuato l’origine del timeout.
6. Esamina le query lente al database e le API esterne
A volte il server web funziona correttamente, ma l’applicazione è in attesa di un altro servizio.
Alcuni esempi comuni sono:
- Una query al database che richiede troppo tempo.
- Un’API esterna che risponde lentamente.
- Pool di worker dell’applicazione esauriti.
- Processi in background che competono per le risorse.
- Blocchi del database che ritardano le richieste.
Esamina i log dell’applicazione, i log delle query lente e le metriche dei servizi per individuare la causa del ritardo.
Se la causa è una query al database, esamina gli indici, i piani di esecuzione delle query e l’utilizzo delle connessioni.
Per le chiamate ad API esterne, configura timeout ragionevoli e una gestione adeguata degli errori. Quando l’applicazione lo supporta, può essere preferibile gestire in modo asincrono le attività di lunga durata.
7. Contatta il tuo provider di hosting
Se non riesci a risolvere l’errore 504 Gateway Timeout, contatta il tuo provider di hosting e fornisci gli elementi che hai raccolto.
Indica il dominio interessato, quando è iniziato il problema, se si verifica a intermittenza e gli eventuali messaggi di log pertinenti.
Segnala le modifiche recenti alla configurazione dell’applicazione, del database, della CDN o del reverse proxy.
Un provider di hosting può aiutarti a esaminare limitazioni delle risorse e problemi infrastrutturali al di fuori delle tue possibilità di accesso amministrativo.
Errori gateway 502 e 504: qual è la differenza?
Questi errori sono correlati, ma indicano problemi upstream diversi.
| Errore | Significato |
|---|---|
| 502 Bad Gateway | Un gateway ha ricevuto una risposta non valida da un server upstream |
| 504 Gateway Timeout | Un gateway non ha ricevuto in tempo la risposta necessaria da un server upstream |
Per esempio, un’applicazione che chiude inaspettatamente una connessione può causare un errore 502, mentre un’applicazione che impiega troppo tempo a rispondere può causare un errore 504.
Come prevenire gli errori 504 Gateway Timeout
Non tutti i timeout possono essere evitati, ma una buona gestione dell’infrastruttura aiuta a ridurne la frequenza.
- Monitora i tempi di risposta dell’applicazione e l’utilizzo delle risorse.
- Esamina le query lente al database.
- Utilizza una cache adeguata per i contenuti richiesti frequentemente.
- Configura timeout appropriati per i server upstream e l’applicazione.
- Monitora i servizi backend e la disponibilità dei worker.
- Testa le modifiche importanti alla configurazione prima di distribuirle.
L’aumento dei limiti di timeout dovrebbe essere una scelta ponderata, non il primo passo nella risoluzione del problema.
Domande frequenti
Sì. HTTP 504 è un codice di stato lato server che indica che un gateway o un proxy non ha ricevuto in tempo una risposta da un server upstream.
Di solito no. La cache del browser non risolve il problema di un server backend sovraccarico o che non risponde. Provare un altro browser o un’altra connessione può però aiutarti a escludere problemi circoscritti.
Può esserlo. Un sovraccarico temporaneo o una richiesta lenta al backend possono risolversi rapidamente, mentre i timeout ricorrenti indicano un problema che richiede un’indagine.
Sì. WordPress e altre applicazioni possono presentare errori 504 quando le query al database, l’elaborazione PHP o i servizi upstream richiedono troppo tempo.
Solo se l’applicazione ha effettivamente bisogno di più tempo e gli altri limiti dell’infrastruttura lo consentono. Determina prima perché la risposta del backend è in ritardo.
Conclusione
Un errore 504 Gateway Timeout significa che un gateway ha atteso troppo a lungo la risposta di un server upstream.
I visitatori possono verificare se il problema è temporaneo, mentre gli amministratori dovrebbero esaminare i log, le risorse del server, le prestazioni dell’applicazione e le impostazioni del proxy.
La soluzione più affidabile è individuare la causa del ritardo, anziché aumentare i limiti di timeout o riavviare i servizi senza aver prima verificato il problema.
