L’errore 504 Gateway Timeout compare quando un gateway o un proxy non riceve entro il tempo previsto la risposta del servizio a monte. La richiesta è arrivata all’infrastruttura, ma un componente successivo ha impiegato troppo tempo.
Questa guida approfondisce errore 504 Gateway Timeout con una procedura progressiva e reversibile. Non inviare password, codici 2FA, token, chiavi private o file di configurazione completi nei ticket.
Che cosa significa
Il timeout visibile nel browser può essere inferiore al tempo massimo configurato in PHP. Anche se lo script continua o termina dopo, il proxy può aver già chiuso la richiesta.
Aumentare i timeout può nascondere query inefficienti, chiamate API senza risposta, processi bloccati o operazioni che dovrebbero essere eseguite in background.
Come riconoscere il problema
- Il 504 compare durante importazioni o esportazioni.
- Una pagina semplice funziona ma un report o checkout no.
- Il problema si verifica a intervalli regolari con cron o backup.
- La richiesta termina dopo un tempo quasi costante.
- La CDN mostra il timeout mentre l’origine continua a lavorare.
Cause più frequenti
1. Script PHP lento
Un’operazione elabora troppi dati o attende risorse senza completare entro la finestra del proxy. Verifica questa ipotesi usando il messaggio completo e i dati dell’orario interessato, senza basarti soltanto sul testo mostrato dal browser o dall’applicazione.
2. Query database inefficiente
Tabelle grandi, indici mancanti o query ripetute possono bloccare la risposta. Verifica questa ipotesi usando il messaggio completo e i dati dell’orario interessato, senza basarti soltanto sul testo mostrato dal browser o dall’applicazione.
3. API esterna non disponibile
Plugin e integrazioni possono attendere servizi remoti senza timeout adeguati. Verifica questa ipotesi usando il messaggio completo e i dati dell’orario interessato, senza basarti soltanto sul testo mostrato dal browser o dall’applicazione.
4. Processi simultanei
Cron, backup, scansioni, importazioni e traffico possono concorrere per le stesse risorse. Verifica questa ipotesi usando il messaggio completo e i dati dell’orario interessato, senza basarti soltanto sul testo mostrato dal browser o dall’applicazione.
5. Timeout non coerenti
CDN, web server, PHP e applicazione possono avere soglie differenti. Verifica questa ipotesi usando il messaggio completo e i dati dell’orario interessato, senza basarti soltanto sul testo mostrato dal browser o dall’applicazione.
6. Lock o deadlock applicativo
Transazioni, file lock o code possono impedire il completamento della richiesta. Verifica questa ipotesi usando il messaggio completo e i dati dell’orario interessato, senza basarti soltanto sul testo mostrato dal browser o dall’applicazione.
Diagnosi passo per passo
- Misura il tempo. Registra dopo quanti secondi compare il 504 e confrontalo tra richieste. Salva il risultato e confrontalo con il passaggio successivo; in questo modo potrai distinguere una causa locale da una configurazione del servizio.
- Controlla i log. Cerca max execution time, slow query, cURL timeout, errori database e processi terminati. Salva il risultato e confrontalo con il passaggio successivo; in questo modo potrai distinguere una causa locale da una configurazione del servizio.
- Disattiva il componente sospetto in staging. Verifica plugin o integrazione senza compromettere il sito pubblico. Salva il risultato e confrontalo con il passaggio successivo; in questo modo potrai distinguere una causa locale da una configurazione del servizio.
- Controlla cron e attività pianificate. Individua processi che coincidono con l’orario del problema. Salva il risultato e confrontalo con il passaggio successivo; in questo modo potrai distinguere una causa locale da una configurazione del servizio.
- Verifica il database. Controlla dimensioni, autoload, query lente e stato delle tabelle. Salva il risultato e confrontalo con il passaggio successivo; in questo modo potrai distinguere una causa locale da una configurazione del servizio.
- Analizza le chiamate esterne. Imposta log e timeout per API, webhook, gateway e feed. Salva il risultato e confrontalo con il passaggio successivo; in questo modo potrai distinguere una causa locale da una configurazione del servizio.
- Confronta origine e proxy. Determina quale livello chiude per primo la connessione. Salva il risultato e confrontalo con il passaggio successivo; in questo modo potrai distinguere una causa locale da una configurazione del servizio.
Metodo sicuro di intervento
Prima di modificare la configurazione, registra lo stato iniziale: indirizzo o funzione coinvolta, messaggio completo, data e ora, ultima modifica nota e risultato da un secondo dispositivo, rete o strumento. Una diagnosi ripetibile è più utile di molti tentativi eseguiti contemporaneamente.
Applica una sola correzione alla volta e conserva una copia dei file, dei record o dei valori precedenti. Dopo ogni intervento ripeti esattamente il test originale e controlla i log relativi allo stesso intervallo temporale. Se il risultato cambia, annota quale modifica lo ha prodotto.
Evita disattivazioni globali di firewall, WAF, TLS, cache o sistemi di sicurezza. Quando serve una eccezione, deve essere limitata all’URL, al parametro, al processo o al servizio realmente interessato.
Procedura di risoluzione
- Ottimizza la procedura. Usa batch, paginazione, code o processi asincroni per attività lunghe. Dopo la modifica ripeti lo stesso test, controlla il log e verifica che non siano comparsi effetti collaterali.
- Correggi le query. Riduci dati caricati, aggiungi indici appropriati e rimuovi query duplicate. Dopo la modifica ripeti lo stesso test, controlla il log e verifica che non siano comparsi effetti collaterali.
- Imposta timeout applicativi. Le chiamate esterne devono fallire in modo controllato e non bloccare l’intera pagina. Dopo la modifica ripeti lo stesso test, controlla il log e verifica che non siano comparsi effetti collaterali.
- Separa le attività pesanti. Evita che backup e importazioni coincidano con picchi di traffico. Dopo la modifica ripeti lo stesso test, controlla il log e verifica che non siano comparsi effetti collaterali.
- Aggiorna plugin e integrazioni. Versioni recenti possono correggere loop, query e timeout. Dopo la modifica ripeti lo stesso test, controlla il log e verifica che non siano comparsi effetti collaterali.
- Aumenta un limite solo con motivazione. Modifica la soglia pertinente dopo aver individuato il collo di bottiglia. Dopo la modifica ripeti lo stesso test, controlla il log e verifica che non siano comparsi effetti collaterali.
- Ripeti il test con monitoraggio. Controlla log e risorse mentre esegui la stessa operazione. Dopo la modifica ripeti lo stesso test, controlla il log e verifica che non siano comparsi effetti collaterali.
Controlli finali
- L’operazione termina prima del timeout.
- Non compaiono nuove slow query o cURL timeout.
- Le pagine normali restano reattive.
- Cron e attività pesanti non si sovrappongono.
- La CDN riceve risposta valida dall’origine.
Prevenzione
- Suddividi lavori lunghi in batch.
- Imposta timeout per servizi esterni.
- Monitora query e cron.
- Programma backup fuori dai picchi.
- Mantieni un ambiente staging.
Errori da evitare
- Non aumentare tutti i timeout al valore massimo.
- Non eseguire importazioni massive via browser senza necessità.
- Non lasciare API senza timeout.
- Non ripetere la richiesta mentre la precedente è ancora attiva.
- Non confondere 504 e 502.
Come documentare la verifica
Conserva una breve nota con configurazione iniziale, risultato di ogni controllo e modifica applicata. Inserisci sempre data e ora, perché cache, log, code, rate limit e processi pianificati possono cambiare nel tempo. Questa documentazione facilita il rollback e permette all’assistenza di evitare verifiche già eseguite.
Quando confronti due test, usa le stesse condizioni: stesso URL o destinatario, stesso file, stesso client e stessa rete quando possibile. Se cambi più variabili, il risultato non permette di individuare con certezza la causa.
Controllo incrociato
Dopo la correzione esegui almeno un controllo indipendente. Per un sito confronta browser, risposta HTTP e log; per DNS interroga autoritativo e resolver pubblico; per la posta confronta Webmail, intestazioni e Track Delivery; per PHP verifica il valore effettivamente applicato al dominio. Un solo indicatore può essere influenzato da cache o configurazioni locali.
Se il problema ricompare, evita ulteriori modifiche e raccogli nuovamente i dati. La ricorrenza può indicare un processo pianificato, un limite raggiunto, una dipendenza esterna o una configurazione che viene rigenerata automaticamente.
Quando contattare l’assistenza Xlogic
Apri un ticket quando il problema persiste dopo i controlli di base, coinvolge più servizi oppure richiede log e configurazioni non disponibili nel pannello. Indica:
- URL e funzione
- durata prima dell’errore
- orario
- log PHP o applicativo
- attività pianificate contemporanee
Non inviare credenziali. Per iniziare la diagnosi sono sufficienti dati tecnici, orari, URL, codici e messaggi di errore.
Fonti tecniche ufficiali
Domande frequenti su errore 504 Gateway Timeout
Un 504 è sempre un problema di rete?
No. Spesso il servizio a monte risponde troppo lentamente per query, PHP o API.
Aumentare il timeout è una soluzione definitiva?
Non sempre. Può soltanto prolungare l’attesa e nascondere un processo inefficiente.
Un backup può causare il 504?
Può contribuire se usa molte risorse o si sovrappone all’operazione interessata.
Perché il processo continua dopo l’errore?
Il proxy può chiudere la connessione mentre PHP o un processo in background prosegue.
Che cosa devo indicare nel ticket?
URL, orario, durata, operazione, log e attività concomitanti.