Błąd 502 (Bad Gateway) pojawia się, gdy serwer pośredniczący nie otrzymuje poprawnej odpowiedzi od serwera „upstream” (aplikacji lub serwera źródłowego). Dla użytkownika wygląda to jak awaria strony, jednak w praktyce najczęściej chodzi o kłopot z komunikacją między warstwami: CDN/proxy/load balancerem a backendem. W tym poradniku pokażę, jak ustalić, skąd bierze się 502 i co zwykle oznacza w zależności od architektury (np. Nginx, Cloudflare, ALB, Kubernetes). Dostaniesz też konkretne wskazówki, jakie dane zebrać, aby diagnoza była szybka i nie opierała się na domysłach. Gdy 502 występuje wyłącznie u Ciebie, zaczniesz od prostych testów po stronie klienta, a jeśli ma charakter globalny, skupisz się na logach i kondycji usług. Czytaj dalej, aby przejść od objawów do przyczyny i obrać właściwy kierunek naprawy.
Co oznacza błąd 502 i jak go rozpoznać?
Błąd 502 oznacza, że serwer pośredniczący (np. reverse proxy, CDN, load balancer) nie był w stanie przetworzyć albo poprawnie zinterpretować odpowiedzi z backendu („upstream”). Rolę „bramy” może pełnić Nginx/Apache jako proxy, Cloudflare, AWS ALB/ELB albo Ingress w Kubernetes, a „upstreamem” bywa np. PHP-FPM, Node.js, Gunicorn/Uvicorn, Tomcat lub serwis API po HTTP/TCP. W odróżnieniu od 500 (błąd aplikacji), 503 (brak dostępności) i 504 (timeout), 502 częściej sugeruje „wadliwą” odpowiedź albo zerwane połączenie pomiędzy warstwami. Dotyczy to nie tylko stron WWW, ale również API i aplikacji mobilnych, gdzie w narzędziach typu curl/Postman zobaczysz np.
HTTP/1.1 502 Bad Gateway
.
Źródło 502 nierzadko da się wywnioskować z ekranu błędu albo z nagłówków odpowiedzi widocznych w DevTools (Network). W nagłówkach wypatruj pól takich jak `server`, `via`, `cf-ray` lub `x-cache`, bo zwykle podpowiadają, czy błąd generuje Nginx na originie, CDN czy load balancer. W logach proxy administratorzy często trafiają na komunikaty w rodzaju `connect() failed (111: Connection refused)` albo `upstream prematurely closed connection`, co wskazuje na problem z połączeniem do upstreamu lub nagłe przerwanie odpowiedzi. Zdarza się też, że odświeżenie (F5) na moment pomaga, co bywa tropem w stronę restartu procesu backendu albo wahań obciążenia. Zanim przejdziesz do naprawy, warto zanotować czas, pełny URL, czy problem dotyczy całej domeny czy tylko jednej podstrony oraz czy występuje w różnych sieciach (Wi‑Fi/LTE).
Jakie są najczęstsze przyczyny błędu 502 po stronie serwera?
Najczęstsze przyczyny 502 po stronie serwera sprowadzają się do sytuacji, w której upstream nie działa, nie nasłuchuje na porcie albo przerywa połączenie w trakcie generowania odpowiedzi. Jeśli backend padł (np. zatrzymany PHP-FPM lub proces aplikacji), proxy nie zestawi połączenia z upstreamem i zwróci 502, często z błędami „connection refused” lub „no live upstreams”. Kłopot zwykle narasta przy przeciążeniu CPU/RAM lub przy ubijaniu procesów przez OOM (Out Of Memory), gdy backend zaczyna resetować sesje TCP. W PHP-FPM typowym źródłem 502 jest brak dostępnych procesów (np. `pm.max_children`) albo timeouty, przez co kolejne żądania nie mają przez kogo zostać obsłużone. Zdarzają się też błędy aplikacji, które kończą połączenie przed wysłaniem poprawnej odpowiedzi HTTP, a proxy odczytuje to jako nieprawidłową odpowiedź.
502 bywa również konsekwencją błędów konfiguracji i zależności między warstwami, nawet jeśli aplikacja „teoretycznie” działa. Niepoprawnie ustawiony `proxy_pass`/`fastcgi_pass` (zły port, socket lub host) potrafi zwrócić natychmiastowe 502 po zmianach, mimo że upstream jest uruchomiony. Problemy z TLS między bramą a upstreamem (np. błąd handshake, niezgodny SNI lub brak pełnego łańcucha certyfikatu po aktualizacji) także mogą kończyć się 502 zamiast jasnego komunikatu. W części wdrożeń 502 pojawia się przy limitach warstwowych, np. zbyt dużych nagłówkach (rozrośnięte cookies) lub odpowiedziach, które wpadają w limity buforów proxy. Rzadziej winne są kwestie sieciowe, takie jak firewall blokujący połączenia bramy do backendu albo przepełnienie NAT/conntrack przy dużym ruchu, co powoduje falujące zrywanie połączeń.
Typowe scenariusze występowania błędu 502 w różnych architekturach
Błąd 502 najczęściej występuje w architekturach, w których ruch przechodzi przez warstwę pośredniczącą (CDN, reverse proxy, load balancer), zanim dotrze do aplikacji. Na Cloudflare lub innym CDN 502 może wynikać z problemu po stronie origin, łącza CDN↔origin albo reguł WAF, a ekran błędu bywa uzupełniony o identyfikator Ray ID. W przypadku Nginx jako reverse proxy 502 zwykle oznacza, że PHP-FPM/Node/Gunicorn nie odpowiedział albo zresetował połączenie, co często zdarza się w aplikacjach typu WordPress, Laravel czy Django. Jeśli 502 pojawia się na warstwie CDN, zacznij od ustalenia, czy problem dotyczy originu, połączenia do originu czy reguł bezpieczeństwa (WAF/rate limiting), bo każda z tych przyczyn wymaga innego kierunku naprawy.
W środowiskach chmurowych i rozproszonych 502 bywa „objawem” kłopotów ze zdrowiem targetów albo z routingiem. W AWS ALB/ELB 502 może wynikać z tego, że instancja w Target Group odpowiada w nieprawidłowy sposób, pojawia się problem z TLS lub health check jest skonfigurowany błędnie (warto sprawdzać Target Group → Health oraz logi ALB). W Kubernetes 502 często oznacza brak zdrowych endpointów (pody niegotowe) albo kierowanie ruchu na niewłaściwy port, co da się szybko potwierdzić przez `kubectl get endpoints`, `kubectl describe ingress` oraz logi kontrolera Ingress. W architekturze mikroserwisów i na API Gateway 502 pojawia się także wtedy, gdy awarii ulega konkretny serwis albo trasa ma zbyt agresywne timeouty, przez co błąd dotyczy jedynie wybranych endpointów.
W praktyce 502 potrafi wystąpić również w scenariuszach „okołokonfiguracyjnych”, które nie przypominają klasycznej awarii aplikacji. Po odnowieniu certyfikatów lub zmianach ustawień TLS możliwy jest błąd handshake między bramą a upstreamem (np. niezgodny SNI lub brak pełnego łańcucha), co bywa mapowane na 502. Przy migracjach częstą przyczyną okazują się problemy z DNS i routingiem, gdy brama rozwiązuje upstream do nieprawidłowego IP (np. przez stary rekord A/CNAME i wysoki TTL). Jeśli 502 pojawia się dopiero po zalogowaniu albo tylko na wybranych widokach, sprawdź limity rozmiaru nagłówków (np. rozrośnięte cookies) oraz buforowanie w proxy, ponieważ strona „publiczna” może działać poprawnie mimo błędu na ścieżkach z większą liczbą nagłówków.
Diagnostyka błędu 502: narzędzia i kroki do rozwiązania problemu
Diagnostykę błędu 502 najlepiej rozpocząć od ustalenia, czy problem obejmuje całą domenę, czy tylko konkretną ścieżkę, bo to od razu zawęża obszar poszukiwań. Jeśli błąd występuje wyłącznie na jednym endpointcie (np. upload lub konkretne wywołanie API), podejrzenie zwykle pada na limit rozmiaru, timeout albo pojedynczy upstream. Jeżeli dotyczy całej domeny, częściej chodzi o awarię upstreamu lub konfigurację bramy. Aby szybko rozpoznać warstwę, która zwraca 502, użyj `curl -v` (lub `curl -i`) i przeanalizuj nagłówki odpowiedzi. Nagłówki typu `server`, `via`, `cf-ray`, `x-amz-cf-id`, `x-served-by` czy `x-cache` są praktyczną wskazówką, czy 502 pochodzi z CDN, load balancera, czy proxy na originie.
- Odtwórz błąd w przeglądarce, a w DevTools (Network) zapisz HAR, aby sprawdzić timing, przekierowania oraz to, czy 502 dotyczy pojedynczego requestu (np. XHR), czy całej strony.
- Zweryfikuj DNS i trasę: `dig`/`nslookup` pokaże, na jakie IP wskazuje domena, a `traceroute`/`tracert` pomoże przy podejrzeniach problemów z routingiem lub blokad po drodze.
- Na serwerze podejrzyj logi w czasie rzeczywistym (np. `tail -f /var/log/nginx/error.log` oraz logi aplikacji) i wypatruj fraz typu `upstream`, `connect() failed`, `recv() failed`, `prematurely closed connection`.
- Potwierdź stan usług i portów: `systemctl status …` oraz `ss -ltnp | grep :PORT` (albo weryfikacja socketu) podpowiedzą, czy upstream działa i czy faktycznie nasłuchuje.
- Przetestuj upstream bezpośrednio (np. `curl http://127.0.0.1:PORT/health` albo przez unix socket), żeby oddzielić problem po stronie aplikacji od błędu w konfiguracji proxy.
Jeśli po testach wciąż brakuje jednoznacznej przyczyny, kluczowe staje się zestawienie zdarzeń z obciążeniem i zachowaniem warstw pośredniczących. Sprawdź metryki (np. w Grafanie/Prometheusie) albo przynajmniej `top`/`iostat`, czy 502 występuje równolegle ze skokami CPU, RAM, IO lub liczby połączeń, ponieważ często sugeruje to limity workerów i zasobów. W środowiskach z CDN/WAF/load balancerem warto jednocześnie porównać czas błędu z logami i zdarzeniami warstw ochrony (Firewall Events, Rate Limiting), bo blokady oraz progi potrafią przekierować ruch w sposób, który widać dopiero w danych. Gdy zbierzesz spójny komplet informacji. URL, czas, nagłówki i identyfikatory (np. Ray ID). znacznie łatwiej powiążesz 502 z konkretnym wpisem w logach i szybciej dojdziesz do właściwej naprawy.
Jakie działania podjąć, aby zapobiec powracaniu błędu 502?
Aby ograniczyć ryzyko powracania błędu 502 (Bad Gateway), warto wdrożyć monitoring, sensowne healthchecki oraz przewidywalny proces wdrożeń, tak aby brama (proxy/CDN/LB) nie kierowała ruchu do niegotowego albo przeciążonego upstreamu. Istotne jest wychwytywanie wzrostu 5xx i opóźnień, zanim przerodzą się w falę 502 dla użytkowników lub klientów API. Pomaga również zbieranie danych, które pozwalają sprawnie skorelować pojedynczy request z logami na wszystkich warstwach. Dzięki temu zamiast zgadywania szybciej ustalisz, czy problem dotyczy dostępności backendu, jego wydajności, czy też konfiguracji pośredników.
Najbardziej praktycznym krokiem bywa zewnętrzny monitoring dostępności z alertami przy wzroście 5xx oraz testami kluczowych ścieżek (np. logowanie, checkout, endpoint API), ponieważ sama strona główna może działać mimo 502 na krytycznych funkcjach. Równolegle zbieraj metryki backendu i proxy. liczbę 502/5xx, p95/p99 latency, liczbę aktywnych połączeń, zużycie pamięci oraz kolejki workerów. aby widzieć trendy i powiązania z ruchem. Jeśli 502 pojawia się przy pikach, wdroż autoskalowanie (np. HPA w Kubernetes lub ASG w AWS) oraz właściwe limity/requests CPU/RAM, bo bez marginesu zasobów backend zaczyna zrywać połączenia i brama raportuje 502. Dodatkowo trzymaj w ryzach „drogie” endpointy przez cache’owanie i limitowanie ruchu (np. `limit_req` w Nginx), żeby uniknąć sytuacji, w której pojedynczy wzrost zapytań potrafi rozchwiać upstream.
Na stabilność 502 wpływają również procesy wdrożeniowe oraz obserwowalność między warstwami, ponieważ sporo incydentów pojawia się przy restartach i rolloutach. Wdrażaj z graceful shutdown oraz stosuj strategie blue/green albo canary, tak aby nowe instancje były w pełni gotowe, zanim przejmą ruch, a potencjalny problem objął jedynie niewielki odsetek zapytań. W centralnym logowaniu (np. ELK/Elastic, Loki) dobrze jest przenosić identyfikator requestu (np. `X-Request-ID`) przez proxy do aplikacji, co znacząco ułatwia namierzenie źródła 502 w systemach rozproszonych. Uzupełnij to zwięzłym runbookiem i checklistą incydentową (logi, testy statusu usług, sposób ominięcia CDN, rollback, krytyczne limity), aby skrócić czas przywracania działania w warunkach podwyższonego stresu.
Rola CDN, WAF i load balancerów w generowaniu błędów 502
CDN, WAF i load balancery potrafią zwracać 502, gdy warstwa pośrednia nie otrzymuje poprawnej odpowiedzi z originu lub backendu, albo gdy reguły bezpieczeństwa i routingu przerywają komunikację. W praktyce 502 bywa skutkiem kombinacji: niestabilnego originu, źle ustawionych healthchecków, problemów TLS między warstwami lub filtrów WAF, które modyfikują przepływ requestów. Ma to znaczenie, bo diagnostyka i działania naprawcze zależą od tego, czy 502 „powstaje” na CDN/WAF/LB, czy dopiero na proxy blisko aplikacji. W środowiskach chmurowych często kluczowe jest też, czy load balancer widzi jakiekolwiek zdrowe targety oraz jak interpretuje status „zdrowia” aplikacji.
Najczęstszą pułapką po stronie CDN jest sytuacja, w której origin blokuje adresy IP CDN albo zrywa połączenia, a CDN (np. Cloudflare) mapuje to na 502. W takim przypadku warto przejrzeć zdarzenia w panelu (np. Firewall Events, Rate Limiting) i sprawdzić, czy na originie nie działają blokady na firewallu (UFW/iptables, reguły dostawcy hostingu), które odcinają ruch z sieci CDN. Jeżeli origin przyjmuje ruch tylko z wybranych adresów, dodaj oficjalne zakresy IP CDN do allowlist i zautomatyzuj ich aktualizację, bo inaczej 502 będzie wracał po zmianach po stronie dostawcy. Dodatkowo miej na uwadze, że niespójność cache CDN po zmianach ścieżek na originie może prowadzić do nietrafionych odwołań do nieaktualnych zasobów, dlatego czasem potrzebny jest purge cache dla konkretnych URL-i oraz ujednolicenie reguł cache-control.
Load balancer potrafi wywołać 502, gdy brakuje zdrowych targetów albo healthcheck jest źle zdefiniowany, choć użytkownik widzi, że strona „czasem działa”. Częstą pułapką bywa healthcheck zwracający 301/302 lub wymagający autoryzacji, dlatego praktykuje się osobny endpoint health (zawsze 200 OK), niezależny od logowania i zewnętrznych zależności. Osobna kategoria problemów dotyczy TLS pomiędzy LB a backendem. Gdy warstwy nie zgadzają się co do HTTP/HTTPS, pojawiają się błędy komunikacji, więc warto sprawdzić m.in. `X-Forwarded-Proto` oraz ustawienia wymuszania HTTPS w aplikacji. Dodatkowo WAF potrafi generować fałszywe pozytywy (zwłaszcza przy uploadach lub JSON), dlatego zamiast wyłączać ochronę w całości, lepiej zajrzeć do logów WAF dla konkretnego requestu i przetestować wyłączenie pojedynczej reguły albo tryb „log only”.
Przyczyny błędu 502 po stronie użytkownika: jak je zidentyfikować i rozwiązać?
Po stronie użytkownika błąd 502 najczęściej ma źródło w lokalnych kłopotach z siecią, DNS lub pośrednikami typu VPN/proxy, które zakłócają komunikację z „bramą”. Jeśli łącze gubi pakiety albo zrywa TCP/TLS, warstwa pośrednicząca może nie otrzymać kompletnej odpowiedzi i zwróci 502, mimo że backend działa poprawnie. Bywa też, że przeglądarka trzyma nieaktualny cache przekierowań lub zasobów po zmianach konfiguracji po stronie serwera. Jeżeli 502 występuje tylko na jednym urządzeniu albo w jednej sieci, to wyraźny sygnał, że warto zacząć od diagnostyki lokalnej (sieć/DNS/cache/VPN), a nie od „napraw” po stronie serwera.
- Porównaj zachowanie w innej sieci (np. Wi‑Fi vs LTE) oraz na innym urządzeniu, aby potwierdzić, czy problem ma charakter lokalny.
- Sprawdź, czy VPN lub firmowy proxy nie ingeruje w ruch (np. przez własne certyfikaty TLS). Wyłącz je na chwilę i wykonaj test ponownie.
- Uruchom tryb incognito albo zrób twarde odświeżenie (Ctrl+F5), a następnie wyczyść cache dla domeny, jeśli podejrzewasz błędne przekierowania lub zasoby zapisane w pamięci przeglądarki.
- Gdy podejrzewasz DNS po stronie klienta, wyczyść cache DNS (`ipconfig /flushdns` w Windows) lub ustaw DNS na 1.1.1.1 (Cloudflare) albo 8.8.8.8 (Google), po czym zrestartuj przeglądarkę.
- Wyłącz testowo rozszerzenia (np. adblockery lub dodatki bezpieczeństwa) i porównaj wynik na czystym profilu przeglądarki.
- Jeśli błąd dotyczy API lub integracji, odtwórz request w `curl -v` lub Postmanie i sprawdź, czy klient nie wysyła nietypowych nagłówków (np. `Host`, `Content-Length`) albo nie zrywa połączenia.
W praktyce 502 potrafią prowokować także „graniczne” zachowania po stronie klienta, które podbijają obciążenie albo zwiększają ryzyko usterek komunikacji. Nadmiar równoległych zapytań (np. odświeżanie w pętli lub agresywny skrypt) może obnażyć ograniczoną wydolność backendu i sprawić, że 502 pojawi się dopiero przy większej presji na serwer. Przy kłopotach z TLS dobrze jest również zweryfikować czas systemowy: gdy zegar jest mocno rozjechany, certyfikaty mogą wyglądać na nieważne, co zależnie od pośrednika bywa finalnie raportowane jako 502. Jeżeli po wyłączeniu VPN/proxy, korekcie DNS i odświeżeniu cache błąd znika, przyczyna najczęściej tkwi po Twojej stronie (pośrednik, DNS lub przeglądarka), a nie w samej witrynie.
