Błąd 502 Bad Gateway: przyczyny, diagnostyka serwera i metody naprawy

Błąd 502 Bad Gateway to kod HTTP z grupy 5xx, który oznacza, że serwer pośredniczący (serwer proxy lub brama) otrzymuje nieprawidłową odpowiedź od serwera nadrzędnego albo w ogóle nie może się z nim połączyć. To błąd komunikacji między serwerami, więc problem leży po stronie serwera, a nie przeglądarki. Dla odwiedzającego oznacza to, że strona internetowa przestaje się wyświetlać, choć sam serwer działający w tle może być sprawny. Najczęstsze przyczyny to przeciążenie serwera, zawieszona usługa PHP-FPM, błędna konfiguracja Nginx, nieaktualne rekordy DNS albo zapora sieciowa blokująca ruch.

Z artykułu dowiesz się, jak ustalić źródło problemu, gdy błąd 502 Bad Gateway pojawia się w Nginx, Cloudflare albo WordPressie. Pokazujemy komendy dla Linuksa i Dockera, wyjaśniamy, co oznaczają wpisy w logach, i opisujemy kroki naprawy osobno dla użytkownika i dla administratora.

Czym jest błąd 502 bad gateway i czym różni się od błędu 504

Kod 502 oznacza, że serwer bramy odebrał niepoprawną odpowiedź od innego serwera, nadrzędnego wobec niego (upstream). Błąd 504 Gateway Timeout oznacza co innego: brak jakiejkolwiek odpowiedzi w wyznaczonym limicie czasu. Oba kody należą do grupy 5xx, więc przyczyna jest w infrastrukturze, nie na urządzeniu użytkownika.

Błąd 502 Bad Gateway pojawia się tam, gdzie żądanie przechodzi przez pośrednika, zanim trafi do aplikacji. Takim pośrednikiem jest najczęściej Nginx działający jako reverse proxy, Apache z mod_proxy, load balancer albo content delivery network, np. Cloudflare. Serwer proxy przekazuje żądania klienta do backendu (PHP-FPM, Node.js, Gunicorn) i czeka na prawidłową odpowiedź HTTP. Jeśli serwer nadrzędny zwróci odpowiedź pustą, zniekształconą albo przerwie połączenie w trakcie transmisji, serwer bramy nie potrafi jej obsłużyć i zwraca stronę z kodem błędu 502 Bad Gateway.

Komunikat błędu różni się w zależności od serwera i przeglądarki internetowej: „Error 502”, „HTTP Error 502 - Bad Gateway”, „502 Proxy Error”, „502 Bad Gateway nginx” czy „502 Service Temporarily Overloaded”. Dopisek „nginx” lub „Apache” wskazuje, które oprogramowanie serwera wygenerowało błąd, co ułatwia przeszukiwanie logów.

Przy błędzie 504 serwer nadrzędny wciąż przetwarza zapytanie albo się zawiesił i nie zdążył odpowiedzieć przed upływem limitu, np. proxy_read_timeout w Nginx. Przy błędzie 502 serwer proxy dostaje nieprawidłową odpowiedź: nieczytelną albo niekompletną. Dlatego przy 502 sprawdzaj stabilność i logi procesu aplikacji, a przy 504 wydajność backendu i limity czasowe.

Jak naprawić błąd 502 z perspektywy użytkownika strony

Błąd 502 Bad Gateway to zazwyczaj tymczasowy błąd, a część zgłoszeń znika bez ingerencji w serwer. Krótkie przeciążenie serwera po stronie witryny może powodować przerwy trwające kilkadziesiąt sekund. Zanim uznasz, że błąd leży po stronie serwera, sprawdź, czy nie wynika z powodu problemu komputera lub sieci: nieaktualnej pamięci podręcznej, konfliktu z rozszerzeniem, awarii routera albo błędnych ustawień DNS u dostawcy internetu. Wykonaj następujące kroki:

• Odśwież stronę internetową i wyczyść pamięć podręczną przeglądarki. Odczekaj minutę i załaduj stronę ponownie skrótem Ctrl+F5 (Windows) lub Cmd+Shift+R (macOS), który pomija zapisane zasoby. Jeśli błąd zostaje, wyczyść pamięć podręczną przeglądarki razem z ciasteczkami i danymi przeglądania, a potem otwórz adres w trybie incognito. Wypróbuj inną przeglądarkę: jeśli strona działa w innej przeglądarce i w dowolnej przeglądarce poza jedną, winne jest rozszerzenie albo oprogramowanie antywirusowe filtrujące ruch.
• Wyczyść pamięć podręczną DNS i zrestartuj router. Wpisy DNS są używane przy przeglądaniu stron internetowych w całym systemie, nie tylko w przeglądarce. Polecenie ipconfig /flushdns (Windows) albo sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder (macOS) usuwa nieaktualne wpisy DNS. Pomaga zwłaszcza po zmianie adresu IP serwera, gdy aktualizację DNS widzi już część sieci, ale Twój komputer nadal pyta stary adres. Zrestartuj router i sprawdź, czy inne strony internetowe w tej samej sieci działają, czyli czy masz dostęp do internetu.
• Zmień serwery DNS na publiczne. Ustawienia DNS z adresami 8.8.8.8 (Google) lub 1.1.1.1 (Cloudflare) omijają błędne wpisy u dostawcy internetu. Efekt sprawdzisz, otwierając witrynę, którą chcesz odwiedzić, na dowolnym urządzeniu w innej sieci, np. na telefonie z transmisją mobilną.
• Skorzystaj z archiwalnej wersji witryny. Gdy potrzebujesz treści strony internetowej, a błąd się utrzymuje, sprawdź Wayback Machine, który przechowuje archiwalne kopie witryny. Kopie w Google są niedostępne: Google wycofał link „Kopia” w lutym 2024 roku, a operator cache: we wrześniu 2024 roku.

Jeśli żadna z powyższych metod nie pomaga na różnych urządzeniach i w różnych sieciach, problem nie dotyczy strony użytkownika. To błąd serwera, który musi zdiagnozować administrator. Możesz go zgłosić właścicielowi witryny, podając godzinę wystąpienia i pełny komunikat błędu.

Analiza logów serwera i diagnostyka CLI w systemie Linux

Interpretacja kluczowych komunikatów w logach serwera WWW

Administratorzy powinni zacząć od logów błędów serwera, bo treść wpisu w error.log wskazuje, w którym miejscu komunikacji z upstreamem nastąpiła awaria. W Nginx domyślna ścieżka to /var/log/nginx/error.log.

„Connection refused” oznacza, że Nginx próbował połączyć się z backendem, ale na wskazanym porcie lub adresie nic nie nasłuchiwało. PHP-FPM, Gunicorn albo Node.js jest zatrzymany albo konfiguracja wskazuje zły port.

„No such file or directory” dotyczy zwykle komunikacji przez socket UNIX. Nginx szuka pliku socketa pod wskazaną ścieżką, np. /run/php/php8.3-fpm.sock, a ten nie istnieje. Usługa PHP-FPM jest zatrzymana albo ścieżka w fastcgi_pass nie zgadza się z rzeczywistym położeniem socketa, co często zdarza się po aktualizacji PHP do nowszej wersji.

Najwięcej mówi wpis „upstream prematurely closed connection”: backend przyjął połączenie, ale przerwał je w trakcie wysyłania odpowiedzi. Trzy typowe przyczyny to awaria procesu aplikacji, krytyczny błąd w skrypcie i interwencja OOM killera, czyli mechanizmu Linuksa, który zabija proces zużywający zbyt dużo pamięci RAM. Rozróżnienie wymaga narzędzi CLI.

Narzędzia CLI: weryfikacja procesów, socketów i zużycia pamięci RAM

Status usługi sprawdza systemctl status php8.3-fpm (nazwa zależy od wersji PHP; analogicznie nginx czy gunicorn). Stan active (running) potwierdza, że proces działa. Stan failed lub inactive wyjaśnia komunikat „connection refused” albo „no such file or directory”.

Czy port lub socket faktycznie nasłuchuje, pokaże ss -ltnp (porty TCP) i ss -lxnp (sockety UNIX). Pierwsze polecenie wyświetla nasłuchujące porty z PID-em procesu. Brak wpisu dla portu z konfiguracji Nginx potwierdza przyczynę. Drugie pokazuje ścieżki socketów i pozwala wychwycić niezgodność między konfiguracją Nginx a socketem PHP-FPM.

Przy „upstream prematurely closed connection” sprawdź journalctl -u php8.3-fpm albo journalctl -xe. Dziennik rejestruje restarty usługi, kody wyjścia procesów i wpisy OOM killera z PID-em zabitego procesu. Obecność takiego wpisu jednoznacznie wskazuje brak pamięci RAM. Jeśli powtarza się przy normalnym ruchu, rozwiązaniem bywa zmiana planu hostingowego na większy, bo jeden serwer z małą ilością RAM nie obsłuży szczytowego obciążenia.

Rozwiązywanie problemów w Nginx, PHP-FPM i środowisku Docker

Błąd 502 w Nginx ma trzy główne źródła: błędną konfigurację dyrektyw proxy_pass i fastcgi_pass, zawieszenie procesów PHP-FPM i przekroczenie max_execution_time. W Dockerze dochodzi czwarte: niepoprawne adresowanie usług w sieci wewnętrznej.

Optymalizacja dyrektyw proxy i FastCGI w Nginx

proxy_pass przekazuje żądanie do backendu HTTP, a fastcgi_pass kieruje je do procesu FastCGI, najczęściej PHP-FPM. Pomylenie tych mechanizmów albo wskazanie nieaktualnego adresu, portu czy ścieżki socketa daje natychmiastowy błąd 502.

Osobny przypadek to nazwa hosta w proxy_pass. Nginx domyślnie rozwiązuje ją przez DNS tylko raz, przy starcie. Gdy rekordy DNS backendu zmienią się, np. po migracji na inny serwer, Nginx nadal łączy się ze starym adresem IP aż do przeładowania. Zmienione rekordy DNS bez przeładowania konfiguracji to typowa przyczyna błędu 502 po migracji.

• Niedopasowane bufory nagłówków. Zbyt małe proxy_buffer_size i fastcgi_buffer_size zrywają połączenie, gdy backend zwraca duże nagłówki, np. rozbudowane ciasteczka sesyjne. Log pokazuje wtedy „upstream sent too big header”. Zwiększenie tych dyrektyw, a przy dużych odpowiedziach także fastcgi_buffers, rozwiązuje problem bez zmian w kodzie aplikacji.
• Limity czasu wykonania skryptu. Po przekroczeniu max_execution_time z php.ini PHP-FPM zwraca niepełną odpowiedź, którą Nginx traktuje jako błąd bramy. Wartość musi być spójna z fastcgi_read_timeout, bo rozbieżność obu limitów to częsta przyczyna sporadycznych błędów przy długich operacjach, np. eksporcie dużych raportów.
• Zawieszone procesy PHP-FPM. Pula workerów ma ograniczoną liczbę procesów (pm.max_children). Gdy wszystkie są zajęte wolnymi zapytaniami, kolejni użytkownicy dostają błąd 502. Monitoring statusu puli i restart usługi przywracają obsługę ruchu.
• Limit jednoczesnych połączeń. worker_connections w bloku events określa maksymalną liczbę równoległych połączeń na proces roboczy. Zbyt niska wartość przy dużym ruchu powoduje odrzucanie żądań już na poziomie Nginx.

Po każdej zmianie sprawdź składnię poleceniem nginx -t i przeładuj konfigurację przez systemctl reload nginx. Następnie odśwież stronę i sprawdź, czy błąd 502 Bad Gateway zniknął.

Izolacja problemów komunikacji w sieciach Docker

W kontenerach typowy błąd to odwołanie do localhost wewnątrz kontenera Nginx zamiast do nazwy usługi z docker-compose.yml. Każdy kontener ma własną przestrzeń sieciową, więc localhost wskazuje na sam kontener Nginx, a fastcgi_pass nie znajduje nasłuchującego procesu.

• Poprawne adresowanie usługi. Zamiast fastcgi_pass 127.0.0.1:9000; konfiguracja powinna wskazywać nazwę usługi, np. fastcgi_pass php-fpm:9000;. Docker Compose tworzy wewnętrzny DNS, który mapuje nazwy usług na adresy kontenerów w tej samej sieci.
• Weryfikacja wspólnej sieci. Nginx i PHP-FPM muszą należeć do tej samej sieci zdefiniowanej w docker-compose.yml. Brak wspólnej sieci albo literówka w jej nazwie daje ten sam objaw co błędne proxy_pass.
• Kolejność startu kontenerów. Jeśli Nginx wystartuje przed PHP-FPM, pierwsze zapytania trafią na usługę, która jeszcze nie nasłuchuje. Samo depends_on ustala kolejność, ale nie czeka na gotowość usługi. Do tego służy healthcheck połączony z warunkiem condition: service_healthy.

Diagnostyka i eliminacja błędu 502 w systemie WordPress

W WordPressie błąd 502 wynika najczęściej z wyczerpania pamięci PHP przez wtyczki, zawieszonych zapytań do bazy danych albo krytycznych błędów w motywie. Naprawa wymaga sprawdzenia warstwy aplikacji: wtyczek, motywu i zapytań do MySQL lub MariaDB.

• Włącz logowanie błędów PHP. W wp-config.php ustaw WP_DEBUG i WP_DEBUG_LOG na true. Błędy PHP, w tym krytyczne, które prowadzą do błędu 502, trafią do pliku wp-content/debug.log razem z nazwą wtyczki, funkcji lub linii kodu motywu.
• Podnieś limit pamięci PHP. Gdy debug.log pokazuje „Allowed memory size exhausted”, zwiększ limit w wp-config.php, np. define('WP_MEMORY_LIMIT', '256M');, i równolegle memory_limit w .user.ini lub php.ini. Sama stała WordPressa nie przekroczy limitu ustawionego na serwerze. Sprawdź też max_execution_time, bo import danych czy kopia zapasowa potrafią jednocześnie zużyć dużo pamięci i przekroczyć czas wykonania.
• Wyłącz wadliwe wtyczki i motyw. Bez dostępu do panelu zmień nazwę katalogu w wp-content/plugins/ lub wp-content/themes/ przez SFTP, np. dopisując -disabled. Szybciej działa WP-CLI: wp plugin deactivate <nazwa> albo wp plugin deactivate --all, a wp theme activate z nazwą zainstalowanego motywu domyślnego (np. twentytwentyfive) przywraca stabilny wygląd. Jeśli błąd pojawił się po aktualizacji, przywróć poprzednią wersję wtyczki albo kopię zapasową sprzed zmian.
• Sprawdź zapytania do bazy. Wolne zapytania SQL, np. z ciężkiej wtyczki albo rozbudowanego WP_Query, blokują pulę PHP-FPM podobnie jak wyczerpanie pm.max_children. Polecenie wp db check sprawdza tabele, a wp db repair naprawia uszkodzone, bez logowania do phpMyAdmin.

Stabilność CMS-a przekłada się bezpośrednio na indeksowanie strony, co opisujemy w ostatniej sekcji.

Specyfika błędu 502 Bad Gateway w usłudze Cloudflare

Błąd 502 w Cloudflare ma dwa źródła: awarię po stronie sieci Cloudflare albo błąd 502 zwrócony przez serwer origin, który Cloudflare jedynie przekazuje dalej. Pierwszy przypadek leży poza kontrolą właściciela witryny, drugi wymaga diagnozy backendu opisanej wyżej.

Wygląd strony błędu wskazuje źródło. Strona z brandingiem Cloudflare i numerem Ray ID oznacza, że błąd 502 Bad Gateway wygenerowała sieć Cloudflare. Wtedy warto sprawdzić cloudflarestatus.com i w razie potrzeby zgłosić incydent z numerem Ray ID. Zwykła strona bez elementów Cloudflare, np. z dopiskiem „nginx”, oznacza, że Cloudflare przekazuje błąd 502 wygenerowany przez serwer origin, a przyczyna jest w jego konfiguracji.

Problemy z połączeniem między Cloudflare a originem mają w Cloudflare własne kody z zakresu 520-526, które często myli się z błędem 502:

• Błąd 526 (Invalid SSL certificate) pojawia się w trybie SSL/TLS Full (strict), gdy certyfikat na serwerze origin jest nieważny, wygasły albo samopodpisany. Rozwiązaniem jest certyfikat zaufanego urzędu albo bezpłatny Cloudflare Origin CA. Przełączenie na tryb Full bez weryfikacji traktuj wyłącznie jako test diagnostyczny.
• Błąd 525 (SSL handshake failed) oznacza, że serwer origin nie zestawił sesji TLS, np. przez nieobsługiwane szyfry albo zamknięty port 443.
• Błędy 521 i 522 pojawiają się, gdy firewall serwera blokuje adresy IP Cloudflare. Jeśli firewall (iptables lub UFW) nie przepuszcza oficjalnych zakresów IP Cloudflare, adresy te zostały zablokowane, połączenia są odrzucane i błąd widzą wszyscy odwiedzający witryny. Sprawdzisz to poleceniem iptables -L -n albo ufw status verbose.

Administratorzy powinni sprawdzić też konfigurację zapory sieciowej po stronie Cloudflare. Zbyt restrykcyjne reguły WAF w panelu mogą zablokować ruch, zanim dotrze on do serwera. Dla użytkownika wygląda to jak błąd sieci, choć przyczyna jest zupełnie inna.

Ostatnia grupa przyczyn to DNS. Po zmianie adresu IP serwera rekord A w Cloudflare musi wskazywać nowy origin. Stary rekord kieruje ruch na wyłączony serwer i daje błędy 52x albo 502, dopóki rekordy DNS nie zostaną poprawione.

Wpływ błędu 502 na indeksowanie i crawl budget w SEO

Błędy 5xx, w tym 502, powodują, że Google tymczasowo spowalnia indeksowanie strony. Adresy już zaindeksowane zostają początkowo w indeksie, ale jeśli błąd się utrzymuje, z czasem z niego wypadają. To reakcja ochronna wyszukiwarki: Googlebot traktuje powtarzające się błędy serwera jako sygnał przeciążenia i ogranicza liczbę żądań, żeby nie pogłębiać awarii.

Treści, które Googlebot otrzymuje z adresu zwracającego 5xx, są ignorowane, nawet jeśli strona otwiera się poprawnie z innego serwera czy w przeglądarce użytkownika. Robot wróci po nie później. Po przywróceniu poprawnych odpowiedzi 2xx Google stopniowo zwiększa tempo crawlowania. Krótka awaria trwająca pojedyncze godziny zwykle nie zostawia trwałych strat w wynikach wyszukiwania. Inaczej jest, gdy błąd 502 Bad Gateway wraca codziennie. Problem narasta, gdy błąd powtarza się cyklicznie albo trwa dniami. Każda nieudana próba pobrania strony zużywa crawl budget, który mógłby trafić na nowe lub zaktualizowane podstrony, a przy dłuższej awarii adresy tracą pozycje i w końcu wypadają z indeksu.

Skalę problemu sprawdzisz w Google Search Console: w raporcie „Indeksowanie stron” (status „Błąd serwera (5xx)”) oraz w raporcie „Statystyki indeksowania” w ustawieniach, który pokazuje stan hosta, kody odpowiedzi i średni czas odpowiedzi. Regularnie sprawdzaj te raporty i ustaw zewnętrzny monitoring dostępności, który powiadomi Cię o błędzie, zanim zrobi to spadek ruchu. Stabilny serwer strony internetowej to fundament, bez którego żadne działania w ramach pozycjonowania stron nie przyniosą trwałych efektów. Z naszych audytów wynika, że sporadyczne błędy 502 w godzinach szczytu bywają pierwszym sygnałem, że plan hostingowy przestał wystarczać.

FAQ

Czy błąd 502 Bad Gateway oznacza, że serwer został zhakowany?

Nie. Błąd 502 to standardowy kod HTTP z grupy 5xx, który wskazuje problem w komunikacji między serwerem pośredniczącym a serwerem nadrzędnym. Wynika z przeciążenia, błędu konfiguracji albo zawieszenia usługi, nie z włamania. Jeśli jednak błąd 502 Bad Gateway pojawia się po podejrzanych zmianach w plikach witryny, sprawdź logi dostępu.

Czym różni się błąd 502 Bad Gateway od błędu 500 Internal Server Error?

Błąd 500 Internal Server Error oznacza problem wewnątrz samego serwera, który obsługuje żądanie, np. błąd w skrypcie. Błąd 502 dotyczy komunikacji między serwerem pośredniczącym a serwerem docelowym, który zwrócił niepoprawną odpowiedź albo nie odpowiedział wcale. Inne błędy z grupy 5xx, np. 503 czy 504, mają jeszcze inne przyczyny.