upstream timed out (110: Connection timed out) while reading response header from upstream
Linia din logul de erori nginx care stă în spatele unui 504: nginx a trimis cererea la server și nu a primit nici măcar antetele răspunsului în `proxy_read_timeout`. Caută ce face serverul atât de mult: o operație lungă ținută sincron (un apel extern, un raport) se mută într-un job asincron.
Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la
Ce înseamnă
Mesajul se citește bucată cu bucată: upstream este serverul din spatele nginx, timed out (110: Connection timed out) e codul de sistem pentru timeout, iar while reading response header from upstream spune momentul: conexiunea s-a deschis, cererea a plecat, dar serverul nu a trimis primul octet al răspunsului în timpul permis (implicit 60 de secunde). Linia continuă cu client, server, request și upstream, adică exact URL-ul și instanța implicate.
Clientul vede 504 Gateway Timeout. Dacă mesajul apare cu while connecting to upstream, problema e la deschiderea conexiunii (rețea, firewall, server oprit), nu la durata cererii.
Cel mai des, cererea respectivă face sincron ceva lent: apelează un furnizor extern, generează un PDF, trimite emailuri, rulează o interogare grea. Ia URL-ul din log și măsoară unde se duce timpul.
De ce apare: cauzele frecvente
1Operație lentă făcută în timpul cererii
@PostMapping("/comenzi")
Comanda plaseaza(@RequestBody Cerere c) {
Comanda cmd = repo.save(c.toComanda());
facturi.genereaza(cmd); // 4 secunde, extern
return cmd;
}@PostMapping("/comenzi")
Comanda plaseaza(@RequestBody Cerere c) {
Comanda cmd = repo.save(c.toComanda());
coada.publica(new ComandaPlasata(cmd.id()));
return cmd; // factura o fac workerii
}Clientul are nevoie doar de confirmarea comenzii. Factura poate veni după câteva secunde, prin coadă, fără să țină cererea HTTP deschisă.
2Timeout-uri în ordinea greșită
# nginx: proxy_read_timeout 60s
# aplicația: timeout la furnizor 120s# nginx: proxy_read_timeout 60s
# aplicația: timeout la furnizor 5s, apoi eroare controlatăFiecare strat trebuie să renunțe înaintea celui din fața lui. Altfel aplicația lucrează degeaba la cereri pentru care clientul a primit deja 504.
Repară eroarea, direct în pagină
La plasarea unei comenzi, serverul apelează sincron serviciul de Generare facturi, care răspunde în 4 secunde, iar nginx scrie upstream timed out în log. Scoate factura din drumul cererii: scrierile trebuie să răspundă în sub 300 ms, iar facturile se generează în continuare.
Indiciu
Factura poate fi făcută după ce clientul a primit confirmarea, de cineva care preia sarcina din coadă.
Reparația
1. Șterge conexiunea Server aplicație → Generare facturi. 2. Adaugă Coadă de mesaje cu 2 brokeri și conectează Server aplicație → Coadă. 3. Adaugă Workeri cu 5 instanțe și conectează Coadă → Workeri → Generare facturi.
Rezultat: scrierile răspund în aproximativ 100 ms, iar facturile se fac asincron.
De ce merge
Apelul de 4 secunde era pe drumul fiecărei scrieri. Cu o coadă, serverul salvează comanda, publică un mesaj și răspunde imediat; workerii preiau mesajul și apelează serviciul de facturi în fundal. Latența utilizatorului include doar adăugarea în coadă.
Alte forme ale mesajului
upstream timed out (110: Connection timed out) while connecting to upstreamupstream timed out (110: Operation timed out) while reading response header from upstream
Cum o eviți pe viitor
- Nimic din drumul unei cereri HTTP nu ar trebui să dureze secunde: mută-l într-o coadă.
- Pune timeout-uri pe apelurile externe, mai mici decât timeout-ul proxy-ului.
- Logează durata cererilor și a apelurilor externe, ca să vezi imediat care e lent.
- Nu rezolva prin
proxy_read_timeout 600s.
Întrebări frecvente
Cum aflu ce cerere a dat timeout?
Linia de log conține request: "POST /comenzi HTTP/1.1" și upstream: "http://10.0.1.12:8080/comenzi". Ai URL-ul și instanța; caută în logurile aplicației cererea de la acel moment.
Ce înseamnă varianta „while connecting to upstream”?
Că nginx nu a reușit nici să deschidă conexiunea TCP: serverul e oprit, portul e închis de firewall sau serverul e atât de încărcat încât nu acceptă conexiuni noi.
Erori înrudite
504 Gateway Timeout Proxy-ul sau load balancer-ul a așteptat răspunsul serverului mai mult decât îi permite timeout-ul și a renunțat. Serverul nu e neapărat căzut, ci lent: de obicei din cauza bazei de date supraîncărcate, a unei interogări fără index sau a unui serviciu extern apelat sincron. Un serviciu extern lent blochează toate thread-urile serverului (timeout prea mare) Fiecare cerere apelează sincron un serviciu extern; când acesta devine lent, thread-urile serverului stau blocate până la timeout (adesea 30–60 de secunde sau infinit), iar serverul nu mai poate servi nimic. Pune timeout-uri scurte, potrivite cu durata normală a apelului, plus circuit breaker și fallback. Plasarea comenzii durează secunde: emailul de confirmare e trimis sincron, în cerere Cererea de plasare a comenzii așteaptă furnizorul de email (SMTP sau API), care răspunde în secunde, deci clientul așteaptă și el. Emailul nu trebuie să fie gata înainte de răspuns: publică un eveniment în coadă și lasă workerii să-l trimită. Învață System Design de la zero, cu exerciții la fiecare lecție
Curs System Design: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 10 lecții sunt gratuite.
