Come appare il messaggio
2026/10/29 09:14:02 [error] 1234#1234: *5678 upstream timed out (110: Connection timed out) while reading response header from upstream, client: 203.0.113.5, server: example.com, request: "POST /api/export HTTP/1.1", upstream: "fastcgi://unix:/run/php/php8.3-fpm.sock"Cause frequenti
- La richiesta è semplicemente lenta: una query lunga, un export, un report o la chiamata a un'API esterna lenta.
- Tutti i worker PHP-FPM sono occupati (
pm.max_childrenraggiunto) e le nuove richieste aspettano in coda. - Il valore predefinito di
fastcgi_read_timeoutoproxy_read_timeout, 60 secondi, è più breve di quanto serve. - Il backend si blocca, ad esempio in un deadlock o aspettando un file bloccato.
- Per “while connecting to upstream”: un problema di firewall o di rete tra nginx e il backend.
Verifica
- Quale parte è scaduta? Leggi la fine della riga di log
grep -i 'timed out' /var/log/nginx/error.log | tail -n 20 - Sono occupati tutti i worker PHP-FPM?
grep -i 'max_children' /var/log/php8.3-fpm.log | tail -n 5 - Quanto impiega il backend per l'URL lento?
curl -s -o /dev/null -w '%{time_total}s\n' https://example.com/api/export - Il backend è raggiungibile?
systemctl status php8.3-fpm
Soluzione
- Prima capisci perché la richiesta è lenta (database, API esterna) e risolvi quello. Un timeout più lungo nasconde solo il problema.
- Se il compito richiede davvero più tempo, alza il limite solo per quella location:
fastcgi_read_timeout 300;oproxy_read_timeout 300;. - Aumenta
pm.max_childrennel pool PHP-FPM se i worker sono il collo di bottiglia e la RAM lo permette. - Sposta i lavori lunghi in background (cron, coda) e fai rispondere subito la pagina.
- Per “connecting to upstream”: controlla firewall e indirizzo del backend.
Scenario tipico
Nel backend di WordPress avvii l'esportazione dei prodotti WooCommerce. Dopo esattamente 60 secondi il browser mostra "504 Gateway Time-out" e nel log errori di nginx compare upstream timed out (110) while reading response header from upstream. Con 500 prodotti l'esportazione funzionava, ora ce ne sono 8000. Guarda prima l'access log: con $request_time e $upstream_response_time nel log_format vedi quali URL sono davvero lente.
Domande frequenti
Ho alzato il timeout in nginx ma gli utenti vedono ancora un errore. Perché?
Altri livelli hanno limiti propri: il max_execution_time di PHP, un load balancer o una CDN. Cloudflare, per esempio, chiude la connessione dopo circa 100 secondi.
504 è la stessa cosa di 502?
No. 502 significa che il backend ha dato una risposta non valida o non era raggiungibile. 504 significa che non ha risposto in tempo.
Quale timeout vale nel mio caso, fastcgi_read_timeout o proxy_read_timeout?
Dipende da come nginx passa la richiesta al backend. Con fastcgi_pass (PHP-FPM) conta fastcgi_read_timeout, con proxy_pass conta proxy_read_timeout. Entrambi misurano la pausa tra due letture, non la durata totale della richiesta. Controlla sempre quale direttiva è attiva nella location con nginx -T.
Come misuro quanto impiega davvero il backend?
Aggiungi $request_time e $upstream_response_time al log_format e ordina l'access log per i valori più alti. Così capisci se poche URL sono fuori scala o se è tutto lento, prima di alzare qualsiasi timeout.
Lo script continua a girare nel backend dopo che nginx ha chiuso la connessione?
Spesso sì. nginx chiude solo la propria connessione verso il backend; PHP-FPM può lasciar finire lo script o fermarlo a max_execution_time. Un'esportazione può quindi completarsi in background, e un nuovo clic su "riprova" la fa partire una seconda volta.