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

502 Bad Gateway

Pe scurt

Proxy-ul sau load balancer-ul din fața aplicației a primit un răspuns invalid de la server, de obicei pentru că procesul aplicației a căzut, a repornit sau nu ascultă pe portul configurat. Verifici întâi logurile aplicației și ale proxy-ului, apoi health check-ul care trebuie să scoată instanțele moarte din rotație.

Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la

Ce înseamnă

502 Bad Gateway nu vine de la aplicația ta, ci de la componenta din fața ei: nginx, un load balancer (ALB, HAProxy), un API gateway sau CDN-ul. „Gateway” înseamnă intermediarul, iar „bad” înseamnă că acesta a încercat să ia răspunsul de la server (upstream) și a primit ceva inutilizabil: conexiunea s-a închis, răspunsul a fost incomplet sau procesul nu mai exista.

Cauzele tipice sunt un proces căzut (crash, OOM kill, deploy în curs), un port greșit în configurația proxy-ului sau o instanță moartă pe care load balancer-ul încă o folosește pentru că health check-ul e dezactivat sau prea rar.

Ca să găsești locul, pornește de la proxy: în logul de erori nginx apare linia exactă (connect() failed, upstream prematurely closed connection), cu adresa upstream-ului. Apoi te uiți în logurile instanței respective la momentul acela. Dacă eroarea apare doar pentru o parte din cereri, e aproape sigur o singură instanță bolnavă rămasă în rotație.

De ce apare: cauzele frecvente

1Load balancer fără health check

Greșit
upstream app {
    server 10.0.1.11:8080;
    server 10.0.1.12:8080;   # căzut, dar tot primește cereri
    server 10.0.1.13:8080;
}
Corect
upstream app {
    server 10.0.1.11:8080 max_fails=3 fail_timeout=10s;
    server 10.0.1.12:8080 max_fails=3 fail_timeout=10s;
    server 10.0.1.13:8080 max_fails=3 fail_timeout=10s;
}

Fără verificarea stării, proxy-ul trimite în continuare o treime din cereri la instanța moartă, iar acelea primesc 502. Cu max_fails (sau un health check activ la ALB / HAProxy) instanța e scoasă din rotație.

2Portul din proxy nu e cel pe care ascultă aplicația

Greșit
location / {
    proxy_pass http://127.0.0.1:3000;
}
# aplicația pornește pe 8080
Corect
location / {
    proxy_pass http://127.0.0.1:8080;
}

Proxy-ul încearcă un port pe care nu răspunde nimeni, deci nu primește niciun răspuns valid. Portul din configurație trebuie să fie exact cel pe care ascultă procesul.

3Procesul cade sub încărcare (lipsă de memorie)

Greșit
# docker inspect app --format '{{.State.OOMKilled}}'
true
Corect
# limită de memorie potrivită + heap configurat sub ea
docker run -m 1g -e JAVA_OPTS='-Xmx700m' magazin-app

Când kernelul omoară procesul pentru memorie, conexiunile deschise se închid brusc și proxy-ul răspunde 502. Dimensionează memoria și urmărește repornirile.

Repară tu

Repară eroarea, direct în pagină

Load balancer-ul magazinului are health check-ul dezactivat. Când pică un server, o parte din cumpărători primesc 502 Bad Gateway. Repară configurația astfel încât căderea oricărei instanțe a serverului să nu mai piardă cereri.

Indiciu

Nu ai nevoie de componente noi: uită-te la proprietățile load balancer-ului.

Alte forme ale mesajului

  • 502 Bad Gateway nginx
  • HTTP 502 Bad Gateway
  • Error 502 Bad Gateway (Cloudflare)
  • 502 Bad Gateway: The server returned an invalid or incomplete response.

Cum o eviți pe viitor

  • Activează health check-ul pe load balancer, pe un endpoint ușor (/health), cu interval scurt.
  • Ține cel puțin 2 instanțe, ca una căzută să nu oprească serviciul.
  • La deploy, scoate instanța din rotație înainte să o oprești (connection draining).
  • Alertează pe procentul de răspunsuri 5xx de la load balancer, nu doar pe erorile din aplicație.

Întrebări frecvente

Care e diferența dintre 502 și 504?

La 502 proxy-ul a primit un răspuns invalid sau conexiunea s-a închis. La 504 nu a primit niciun răspuns în timpul permis. 502 indică de obicei un proces căzut, 504 un server sau o bază de date lentă.

De ce apare 502 doar uneori?

De obicei o singură instanță e bolnavă și primește o parte din cereri prin round robin. Uită-te în logul proxy-ului la adresa upstream-ului din liniile cu eroare: se repetă aceeași adresă.

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.