...
Eroare System Design · Erori HTTP la proxy și load balancer: 502, 503, 504

upstream timed out (110: Connection timed out) while reading response header from upstream

Pe scurt

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

Greșit
@PostMapping("/comenzi")
Comanda plaseaza(@RequestBody Cerere c) {
    Comanda cmd = repo.save(c.toComanda());
    facturi.genereaza(cmd);  // 4 secunde, extern
    return cmd;
}
Corect
@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ă

Greșit
# nginx: proxy_read_timeout 60s
# aplicația: timeout la furnizor 120s
Corect
# 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ă tu

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ă.

Alte forme ale mesajului

  • upstream timed out (110: Connection timed out) while connecting to upstream
  • upstream 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

← Toate erorile System Design

Tudor Andrei Dumitrescu
Cine a explicat eroarea

Tudor Andrei Dumitrescu

Senior Software Developer · fondatorul Academiei Programatorilor

LinkedIn
  1. 2019 Junior JavaCognizant Softvision
  2. 2021 Mid JavaCognizant Softvision
  3. 2022 Team LeaderEndava
  4. 2023 Senior Software DeveloperUniCredit
  5. Acum Senior Software DeveloperHCLTech
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu
Certificat de formator autorizatMinisterul Muncii și Ministerul Educației · 2022
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu

Certificat de formator autorizat · Ministerul Muncii și Ministerul Educației · 2022

Din 2020 construiește Academia Programatorilor, iar din 2026 și JoburiIT.ro. Fiecare eroare de aici a fost reprodusă în editorul nostru: codul greșit chiar dă mesajul din titlu, iar reparația chiar funcționează.

Î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.