502 Bad Gateway: co oznacza i jak naprawić błąd 502

Czym jest błąd 502 Bad Gateway?

502 Bad Gateway to kod statusu HTTP, który oznacza, że serwer, który Ci odpowiada, działa jako brama lub proxy i dostał nieprawidłową odpowiedź od serwera, który stoi za nim. Standard HTTP (RFC 9110, sekcja 15.6.3) definiuje go dokładnie tak: serwer, „działając jako brama lub proxy, otrzymał nieprawidłową odpowiedź od serwera wewnętrznego, do którego się odwołał, próbując zrealizować żądanie”.

Większość współczesnych stron ma co najmniej dwie warstwy. Serwer frontowy, taki jak nginx, Apache, Cloudflare lub chmurowy load balancer, przyjmuje Twoje połączenie, a potem przekazuje żądanie do aplikacji upstream, takiej jak PHP-FPM, aplikacja Node.js, pythonowy Gunicorn czy kontener. Gdy upstream nie działa, ulega awarii albo odpowiada czymś, czego proxy nie potrafi użyć, proxy nie ma Ci czego oddać, więc zwraca 502.

Najważniejsze: sama brama działa. Odebrała Twoje żądanie i odpowiedziała. Usterka leży o krok dalej.

Różne oblicza błędu 502

Kod statusu jest wszędzie ten sam, ale wygląd strony zależy od tego, które proxy ją wygenerowało:

Niezależnie od wersji nazwa proxy w stopce strony jest cenną wskazówką: mówi właścicielowi witryny, którą warstwę zbadać.

502 vs 500 vs 503 vs 504: czym się różnią?

Wszystkie kody 5xx oznaczają „problem z serwerem”, ale każdy wskazuje inną warstwę:

Prosta zasada: 502 = upstream dał złą odpowiedź (albo się rozłączył), 504 = upstream nie odpowiedział na czas. Sąsiednie błędy szczegółowo omawiają nasze poradniki: 500 Internal Server Error, 503 Service Unavailable i 504 Gateway Timeout.

Co powoduje błąd 502 Bad Gateway?

• Aplikacja upstream nie działa. PHP-FPM, Node, Gunicorn lub kontener uległ awarii, nie wystartował po wdrożeniu albo właśnie się restartuje.

• Proxy wskazuje złe miejsce. proxy_pass lub fastcgi_pass używa złego portu, starej ścieżki gniazda PHP po aktualizacji albo localhost wewnątrz kontenera Docker.

• Aplikacja pada przy niektórych żądaniach. Jedna podstrona wywołuje zabicie procesu przez brak pamięci albo nieobsłużony wyjątek i połączenie zamyka się przed wysłaniem odpowiedzi.

• Wszystkie procesy robocze są zajęte. PHP-FPM osiągnął limit pm.max_children, więc nowe żądania nie mają dokąd trafić.

• Nagłówki odpowiedzi są za duże. Duże pliki cookie lub rozbudowane nagłówki bezpieczeństwa przepełniają proxy_buffer_size w nginx.

• Niezgodność keep-alive za load balancerem. Aplikacja zamyka bezczynne połączenia wcześniej, niż oczekuje load balancer, więc balancer wysyła żądanie do połączenia, które właśnie się zamyka.

• Zmiana zapory lub sieci między proxy a serwerem źródłowym. Na przykład CDN nie może już dotrzeć do serwera źródłowego, któremu zmienił się adres IP lub reguły zapory.

Jak naprawić błąd 502 jako odwiedzający

Nie naprawisz cudzego serwera, ale te kroki potwierdzą, że problem naprawdę leży po stronie witryny, i usuną rzadkie przyczyny lokalne:

• Odczekaj 30–60 sekund i odśwież stronę (Ctrl + R, na Macu Cmd + R). Wiele błędów 502 trwa tylko tyle, ile wdrożenie lub restart.

• Sprawdź, czy strona nie działa u wszystkich. Narzędzie HTTP Headers od DNS Robot pobiera stronę z naszych serwerów i pokazuje dokładny kod statusu. Jeśli my też dostajemy 502, problem leży po stronie witryny, nie u Ciebie. Test Ping pokaże, czy maszyna serwera w ogóle odpowiada.

• Wymuś pełne odświeżenie i wyczyść pamięć podręczną. Ctrl + Shift + R (Mac: Cmd + Shift + R) pomija kopię z pamięci podręcznej na wypadek, gdyby wyświetlała Ci się nieaktualna strona błędu.

• Wyczyść pamięć podręczną DNS, jeśli strona niedawno zmieniła hosting, aby trafić na nowy serwer. Tutaj znajdziesz instrukcję, jak wyczyścić DNS w każdym systemie.

• Wyłącz VPN i proxy. To Twoje własne proxy może być zawodzącą „bramą”, zwłaszcza w sieciach firmowych.

• Spróbuj innej przeglądarki albo telefonu na danych mobilnych. Jeśli tam działa, wyczyść pliki cookie tej strony.

Jak naprawić błąd 502 Bad Gateway na swoim serwerze

Po stronie serwera 502 to jeden z łatwiejszych błędów do naprawienia, bo proxy prawie zawsze zapisuje dokładnie, co poszło nie tak. Przejdź po kolei przez te cztery kontrole.

1. Przeczytaj log błędów proxy

Wywołaj błąd 502 ponownie, a potem przeczytaj ostatnie linie logu błędów na serwerze proxy:

# nginx
sudo tail -n 50 /var/log/nginx/error.log

# Apache
sudo tail -n 50 /var/log/apache2/error.log    # Debian/Ubuntu
sudo tail -n 50 /var/log/httpd/error_log      # RHEL/Alma/Rocky

Te komunikaty nginx obejmują zdecydowaną większość błędów 502, a każdy z nich wskazuje rozwiązanie:

2. Sprawdź, czy aplikacja upstream działa

# PHP-FPM (dostosuj wersję)
sudo systemctl status php8.3-fpm
sudo journalctl -u php8.3-fpm -n 50

# Node.js pod PM2
pm2 status
pm2 logs --lines 50

# Docker
docker ps -a          # look for containers that keep restarting
docker logs --tail 50 <container>

# Czy proces został zabity za zużycie zbyt dużej ilości pamięci?
dmesg -T | grep -i "killed process"

Jeśli usługa jest zatrzymana, uruchom ją i ustal, dlaczego stanęła: nieudane wdrożenie, błąd składni w nowym wydaniu albo OOM killer, który zabija procesy przy braku pamięci. W logu PHP-FPM komunikat server reached pm.max_children setting oznacza, że wszystkie procesy robocze były zajęte. Zwiększaj pm.max_children tylko wtedy, gdy serwer ma na to RAM; w przeciwnym razie znajdź wolne żądania, które blokują procesy.

3. Upewnij się, że proxy_pass wskazuje właściwy port lub gniazdo

Porównaj to, z czym nginx ma się łączyć, z tym, co faktycznie nasłuchuje:

# Do czego nginx przekazuje żądania?
grep -rn "proxy_pass\|fastcgi_pass" /etc/nginx/sites-enabled/

# Co faktycznie nasłuchuje?
sudo ss -tlnp            # TCP ports and their processes
ls -l /run/php/          # PHP-FPM socket files

Dwie klasyczne niezgodności: po aktualizacji PHP gniazdo nazywa się php8.3-fpm.sock, a nginx nadal wskazuje php8.1-fpm.sock; a wewnątrz Dockera proxy_pass http://localhost:3000 wskazuje sam kontener nginx zamiast aplikacji, więc użyj nazwy usługi z Compose (http://app:3000). Po każdej zmianie uruchom sudo nginx -t i sudo systemctl reload nginx.

4. Prawdziwy przykład: jak dnsrobot.net zwrócił błąd 502

Przydarzyło się to nam 30 września 2026. Po opublikowaniu serii nowych wpisów na blogu dokładnie jeden z nich zwracał 502 Bad Gateway przez nginx 1.24, podczas gdy każda inna strona działała. Aplikacja Next.js stojąca za nginx zwracała tę samą stronę ze statusem 200 OK, gdy odpytaliśmy ją bezpośrednio na porcie 3000. Aplikacja była więc w porządku, a zawodziła brama.

Log błędów nginx podawał odpowiedź w jednej linii: upstream sent too big header while reading response header from upstream. Nagłówki odpowiedzi tej strony miały 4087 bajtów, głównie przez długi nagłówek Content-Security-Policy i nagłówki Link do preloadu. nginx wczytuje pierwszą część odpowiedzi, łącznie ze wszystkimi nagłówkami, do bufora o rozmiarze proxy_buffer_size, który domyślnie wynosi jedną stronę pamięci: 4 KB na naszym serwerze. Zostawało więc tylko 9 bajtów zapasu, a pełny blok nagłówków, razem z linią statusu, go przepełnił.

Rozwiązaniem okazały się trzy linie w bloku location, który przekazuje żądania do aplikacji:

location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_buffer_size 16k;        # room for large headers (was the 4k default)
    proxy_buffers 4 32k;
    proxy_busy_buffers_size 64k;
}

Po nginx -t i przeładowaniu strona zwróciła 200. Wniosek: jeśli tylko niektóre strony zwracają 502, a reszta witryny działa, zanim zaczniesz podejrzewać aplikację, poszukaj limitu rozmiaru, na przykład dużych nagłówków lub dużych plików cookie na tych stronach.

Node.js za load balancerem: losowe błędy 502

Jeśli uruchamiasz Node.js za AWS Application Load Balancer lub podobnym balancerem i widzisz sporadyczne błędy 502 bez żadnych błędów w logach aplikacji, sprawdź limity czasu keep-alive. Serwer HTTP w Node domyślnie zamyka bezczynne połączenia keep-alive po 5 sekundach (server.keepAliveTimeout, w Node.js 26 i wcześniejszych), a AWS ALB utrzymuje bezczynne połączenia otwarte przez 60 sekund. Czasem balancer ponownie używa połączenia dokładnie w chwili, gdy Node je zamyka, i to żądanie wraca jako 502.

Rozwiązanie polega na ustawieniu w aplikacji dłuższego limitu niż w balancerze:

const server = app.listen(3000)
// Musi być dłuższy niż limit bezczynności load balancera (domyślnie w ALB: 60 s)
server.keepAliveTimeout = 65_000
server.headersTimeout = 66_000 // keep slightly above keepAliveTimeout

502 Bad Gateway na Cloudflare

Za Cloudflare najpierw sprawdź, kto wygenerował stronę błędu:

• Strona z logo Cloudflare (Browser ✓ / Cloudflare ✓ / Host ✗): Cloudflare działa, ale nie dostał prawidłowej odpowiedzi od Twojego serwera źródłowego. Sprawdź, czy serwer źródłowy działa, nasłuchuje na portach 443/80 i nie blokuje w zaporze zakresów IP Cloudflare. Przetestuj serwer źródłowy bezpośrednio w Port Checkerze.

• Zwykła strona 502 bez logo: jeśli nie wspomina o cloudflare (na przykład podaje nginx lub Apache), błąd 502 wygenerował Twój własny serwer źródłowy. Skorzystaj z kroków dla serwera opisanych wyżej. Pusta strona z samym napisem „cloudflare” na dole pochodzi od samego Cloudflare, na przykład podczas krótkiego przekierowywania ruchu albo gdy serwer źródłowy wysyła uszkodzoną treść gzip.

• Zmienił się adres IP serwera źródłowego? Jeśli przeniosłeś hosting, zaktualizuj rekord A w DNS Cloudflare. DNS Lookup pokaże, co aktualnie widzi reszta świata.

Czy błąd 502 szkodzi SEO?

Krótka awaria nie szkodzi. Według dokumentacji Google błędy serwera 5xx sprawiają, że roboty Google tymczasowo spowalniają indeksowanie. Strony, które już są w indeksie, początkowo w nim zostają, ale jeśli błędy się utrzymują, Google w końcu usuwa te adresy URL.

Błąd 502 trwający kilka minut podczas wdrożenia jest więc nieszkodliwy. Błąd 502 na ważnych stronach, który trwa dniami albo pojawia się sporadycznie przez tygodnie, może ograniczyć indeksowanie i kosztować pozycje. Monitoruj kluczowe adresy URL i po każdej awarii sprawdź raport Statystyki indeksowania w Search Console.