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 odmówił połączenia, rozłączył się albo wysłał złą odpowiedź, 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 czekają w kolejce gniazda. Większość z nich kończy się potem jako 504; gdy kolejka się zapełni, nginx zapisuje (11: Resource temporarily unavailable) i zwraca 502.
• 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.
• Proxy nie może dotrzeć do upstreamu po zmianie w sieci. Zapora, która odrzuca proxy, albo upstream przeniesiony pod nowy adres IP dają 502 (Connection refused, No route to host). Zapora, która po cichu gubi pakiety, daje zamiast tego 504, a za Cloudflare widać to jako 521 lub 522.

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. Website Down Checker od DNS Robot otwiera stronę z 11 lokalizacji, a Checker nagłówków HTTP pokazuje dokładny kod statusu, który dostaje nasz serwer. Jeśli oni też widzą 502, problem leży po stronie witryny, nie u Ciebie.
• Wymuś pełne odświeżenie skrótem Ctrl + Shift + R (Mac: Cmd + Shift + R) na wypadek, gdyby wyświetlała Ci się zapisana w pamięci podręcznej 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 zwykle zapisuje, co poszło nie tak (wyjątkiem są wyścig keep-alive na load balancerze i własne błędy 502 Cloudflare). Przejdź po kolei przez te trzy kontrole; czwarta część to prawdziwy przykład.

1. Przeczytaj log błędów proxy

Wywołaj błąd 502 ponownie, a potem przeczytaj ostatnie 50 linii logu błędów proxy (polecenia pod tabelą). Każdy z tych komunikatów nginx wskazuje własne rozwiązanie:

# 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

2. Sprawdź, czy aplikacja upstream działa

# PHP-FPM (adjust the version)
sudo systemctl status php8.3-fpm
sudo journalctl -u php8.3-fpm -n 50

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

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

# Was it killed for using too much memory?
sudo 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:

# What is nginx proxying to?
sudo nginx -T 2>/dev/null | grep -n "proxy_pass\|fastcgi_pass"

# What is actually listening?
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).

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 były trzy linie w bloku location, który przekazuje żądania do aplikacji; po nginx -t i przeładowaniu strona zwróciła 200:

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;
}

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 wartości Set-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 w Node 26 i wcześniejszych (server.keepAliveTimeout; Node 24.6 i 22.19 dodały do tego 1 sekundę keepAliveTimeoutBuffer, a następne wydanie główne podnosi wartość domyślną do 65 sekund), 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)
// Must be longer than the load balancer's idle timeout (ALB default: 60s)
server.keepAliveTimeout = 65_000
server.headersTimeout = 66_000 // only needed before Node 18; harmless later

502 Bad Gateway na Cloudflare

Za Cloudflare najpierw sprawdź, kto wygenerował stronę błędu (poradnik Cloudflare o 502/504):

• Strona w stylu Cloudflare (Browser ✓ / Cloudflare ✓ / Host ✗): Twój serwer źródłowy sam zwrócił do Cloudflare 502 lub 504. Napraw to na serwerze źródłowym krokami opisanymi wyżej. Jeśli Cloudflare w ogóle nie może połączyć się z serwerem źródłowym, zobaczysz 521 lub 522, a nie 502.
• Zwykła strona z napisem „502 Bad Gateway” i słowem „cloudflare” pod spodem: pochodzi od samego Cloudflare. Dokumentacja Cloudflare podaje dwie przyczyny: serwer źródłowy wysyła uszkodzoną treść gzip albo treść gzip bez zaktualizowanego Content-Length (do testu wyłącz kompresję na serwerze źródłowym) oraz nagły skok ruchu w jednym centrum danych Cloudflare, który mija sam.
• Strona z nazwą nginx lub Apache: zwykle żądanie dotarło do Twojego serwera z pominięciem Cloudflare, bo rekord DNS nie jest proxowany (szara chmurka) albo oglądasz bezpośrednio serwer źródłowy (chyba że reguła Cache Rule włącza Origin error page pass-through).
• Zmieniłeś hosting? Zaktualizuj rekord A serwera źródłowego w DNS Cloudflare (zły adres IP serwera źródłowego zwykle objawia się jako 521, 522 lub 523). DNS Lookup pokazuje serwer źródłowy tylko dla rekordów z szarą chmurką (tylko DNS); rekordy proxowane odpowiadają własnymi adresami IP Cloudflare.

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.