502 Bad Gateway
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
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;
}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
location / {
proxy_pass http://127.0.0.1:3000;
}
# aplicația pornește pe 8080location / {
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)
# docker inspect app --format '{{.State.OOMKilled}}'
true# limită de memorie potrivită + heap configurat sub ea
docker run -m 1g -e JAVA_OPTS='-Xmx700m' magazin-appCâ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ă 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.
Reparația
1. Atinge Load balancer. 2. Bifează Health check.
Rezultat: instanța căzută e ocolită, iar cererile ajung la celelalte două.
De ce merge
Cu health check-ul activ, load balancer-ul verifică periodic fiecare instanță și o scoate din rotație pe cea care nu răspunde. Cererile merg doar la instanțele vii, deci căderea uneia nu mai produce 502, ci doar o capacitate puțin mai mică.
Alte forme ale mesajului
502 Bad Gateway nginxHTTP 502 Bad GatewayError 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
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. no live upstreams while connecting to upstream nginx a marcat toate serverele din blocul `upstream` ca indisponibile și nu mai are unde trimite cererea, așa că răspunde 502. Apare tipic când există un singur server și acela a căzut sau a dat câteva erori la rând. Repari cu cel puțin două instanțe sănătoase și investighezi de ce au căzut. upstream prematurely closed connection while reading response header from upstream Serverul din spatele nginx a închis conexiunea înainte să trimită răspunsul, deci clientul primește 502. Cel mai des procesul a căzut (excepție netratată, OOM kill) sau a închis o conexiune keep-alive pe care nginx tocmai o refolosea. Caută în logurile aplicației și în `dmesg` exact la momentul erorii. Health checks failed (Target.FailedHealthChecks) Load balancer-ul a marcat instanța ca nesănătoasă pentru că nu a răspuns corect la verificarea periodică (cod greșit, timeout, endpoint inexistent) și nu-i mai trimite trafic. Verifică endpoint-ul de health, timpul de pornire al aplicației și dacă health check-ul depinde inutil de baza de date. Î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.
