Błąd 502 Bad Gateway - co oznacza i jak go naprawić?

Data publikacji: 30 września 2026

Błąd 502 Bad Gateway pojawia się wtedy, gdy serwer stojący pomiędzy przeglądarką a właściwą aplikacją nie potrafi uzyskać od niej prawidłowej odpowiedzi. Zamiast oczekiwanej strony użytkownik widzi krótki komunikat, czasem uzupełniony nazwą serwera, sieci CDN albo dostawcy hostingu.

Taki błąd nie wskazuje od razu jednego uszkodzonego elementu. Źródłem może być zatrzymana aplikacja, przeciążenie, zbyt długi czas odpowiedzi, nieprawidłowy adres serwera docelowego, problem z DNS, zapora albo nieudane wdrożenie. Dlatego skuteczna diagnostyka polega na sprawdzeniu kolejnych warstw, a nie na wielokrotnym odświeżaniu strony lub przypadkowej zmianie ustawień.

Kluczowe wnioski

• Kod 502 zwykle pochodzi z bramy, reverse proxy, load balancera lub CDN, a nie bezpośrednio z przeglądarki.
• Użytkownik może sprawdzić stronę w innej sieci i przeglądarce, ale najczęściej naprawa wymaga działania po stronie serwisu.
• Administrator powinien najpierw ustalić zakres i godzinę awarii, a następnie porównać logi warstwy pośredniej z logami aplikacji.
• Częste przyczyny to niedostępny proces aplikacji, błędny port, timeout, przeciążenie, problem z TLS lub blokada ruchu.
• Po usunięciu usterki warto dodać testy kondycji, monitoring i procedurę bezpiecznego wycofania wdrożenia.

Co dokładnie oznacza 502 Bad Gateway?

W prostej konfiguracji przeglądarka może łączyć się bezpośrednio z serwerem WWW. W wielu współczesnych serwisach żądanie przechodzi jednak przez kilka elementów. Najpierw trafia do sieci CDN, load balancera albo serwera reverse proxy, takiego jak Nginx. Dopiero później jest przekazywane do aplikacji, kontenera, usługi API lub innego serwera nazywanego serwerem nadrzędnym, źródłowym albo upstreamem.

Kod 502 informuje, że pośrednik odebrał żądanie użytkownika, lecz odpowiedź z następnego etapu była nieprawidłowa. Aplikacja mogła w ogóle nie odpowiedzieć, nagle zamknąć połączenie, zwrócić dane w nieoczekiwanym formacie albo prowadzić komunikację na innym porcie niż ten ustawiony w konfiguracji proxy.

W praktyce użytkownik widzi podobny efekt niezależnie od przyczyny: strona się nie otwiera. Dla administratora ważne jest jednak to, że brama działa na tyle, aby zwrócić kod HTTP. Poszukiwania należy więc rozpocząć na odcinku pomiędzy nią a serwerem docelowym.

Czym 502 różni się od 500, 503 i 504?

Kody z grupy 5xx oznaczają problem po stronie infrastruktury obsługującej żądanie, ale opisują różne sytuacje.

• 500 Internal Server Error jest ogólnym błędem samej aplikacji lub serwera, który wykonywał żądanie.
• 502 Bad Gateway oznacza nieprawidłową odpowiedź otrzymaną przez serwer pośredniczący.
• 503 Service Unavailable informuje, że usługa jest chwilowo niedostępna, na przykład z powodu przeciążenia lub prac technicznych.
• 504 Gateway Timeout pojawia się, gdy brama nie otrzyma odpowiedzi od serwera nadrzędnego w wyznaczonym czasie.

Granica pomiędzy tymi kodami nie zawsze jest widoczna dla właściciela strony. Ta sama awaria procesu aplikacji może dać 502 w jednej konfiguracji i 503 w innej. Kod jest wskazówką, a nie pełną diagnozą. Ostateczną odpowiedź zwykle dają logi i test połączenia wykonany bezpośrednio z serwera pośredniczącego.

Co może zrobić zwykły użytkownik?

Jeżeli nie zarządzasz daną stroną, Twoje możliwości są ograniczone, ale kilka prostych testów pozwala ustalić, czy problem dotyczy tylko Twojego urządzenia. Zacznij od odświeżenia strony po minucie lub dwóch. Krótkotrwały błąd może wystąpić podczas restartu aplikacji, automatycznego skalowania albo wdrażania nowej wersji.

Następnie otwórz stronę w oknie prywatnym i sprawdź ją przez inną sieć, na przykład internet mobilny. Możesz też skorzystać z narzędzia czy strona działa, aby porównać wynik z testem wykonywanym z zewnątrz. Jeśli błąd występuje na kilku urządzeniach i w różnych sieciach, najprawdopodobniej nie naprawisz go zmianą ustawień swojej przeglądarki.

Gdy problem pojawia się tylko u Ciebie, wyłącz na chwilę VPN lub ręcznie ustawione proxy i sprawdź, czy błąd nadal występuje. Nie ma natomiast potrzeby od razu usuwać całej historii, zapisanych haseł i wszystkich danych witryn. Błąd 502 rzadko wynika z plików cookie, a pochopne czyszczenie danych może stworzyć dodatkowe niedogodności.

Najczęstsze przyczyny po stronie serwera

Jedną z najczęstszych przyczyn jest zatrzymanie procesu aplikacji. Reverse proxy próbuje wtedy połączyć się z adresem i portem, na którym nic nie nasłuchuje. Podobny efekt daje błędna konfiguracja po migracji: aplikacja uruchamia się na porcie 3001, a Nginx nadal przekazuje ruch na 3000.

Źródłem problemu bywa również przeciążenie. Proces może działać, ale zabraknie mu pamięci, dostępnych wątków, połączeń do bazy lub miejsca na dysku. Jeżeli system operacyjny zakończy aplikację z powodu braku pamięci, brama zobaczy nagle przerwane połączenie i może zwrócić 502.

Inne częste przyczyny to:

• nieprawidłowy adres IP albo port serwera nadrzędnego,
• błędny lub nieaktualny rekord DNS używany wewnątrz infrastruktury,
• problem z certyfikatem TLS pomiędzy proxy a serwerem źródłowym,
• zapora blokująca adresy CDN lub load balancera,
• zbyt małe limity bufora albo nieobsługiwane nagłówki,
• restart kontenera bez gotowego testu kondycji,
• awaria bazy danych lub zewnętrznego API, przez którą aplikacja przestaje odpowiadać,
• niezgodność konfiguracji wprowadzona podczas ostatniego wdrożenia.

Najpierw ustal zakres i czas awarii

Zanim zmienisz konfigurację, zapisz godzinę pierwszego wystąpienia błędu i sprawdź jego zakres. Czy 502 pojawia się na każdej podstronie, tylko przy logowaniu, czy wyłącznie podczas wysyłania formularza? Czy problem dotyczy wszystkich użytkowników, jednego regionu albo tylko żądań kierowanych do konkretnej instancji aplikacji?

Sprawdź stronę główną, jedną statyczną podstronę i funkcję wymagającą działania aplikacji. Jeśli statyczne pliki są dostępne, a dynamiczne adresy zwracają błąd, zawęża to poszukiwania do aplikacji lub połączenia z nią. Jeśli awaria pojawia się co kilka żądań, jedna z instancji za load balancerem może być niesprawna, podczas gdy pozostałe nadal odpowiadają.

Porównaj początek incydentu z ostatnimi zmianami: wdrożeniem, aktualizacją, zmianą rekordów DNS, certyfikatu, reguł zapory lub parametrów hostingu. Zbieżność czasu nie jest dowodem, ale stanowi dobry punkt wyjścia do sprawdzenia konkretnego elementu.

Sprawdź odpowiedź i nagłówki HTTP

Podstawowy test z terminala pozwala potwierdzić kod bez interpretacji komunikatu wyświetlanego przez przeglądarkę:

curl -I https://example.pl

W nagłówkach można czasem rozpoznać, która warstwa wygenerowała odpowiedź. Nazwa CDN, serwera proxy lub identyfikator żądania ułatwią późniejsze odnalezienie wpisu w logach. Test warto wykonać kilka razy oraz z innej sieci. Pojedyncza poprawna odpowiedź nie wyklucza awarii okresowej.

Jeżeli domena niedawno zmieniała serwer, sprawdź także jej publiczne rekordy w narzędziu do sprawdzania strefy DNS. Różne adresy zwracane użytkownikom mogą powodować sytuację, w której część ruchu trafia już do nowej infrastruktury, a część nadal do starej.

Porównaj logi proxy i aplikacji

Najwięcej informacji zwykle znajduje się w logu błędów reverse proxy oraz w logu aplikacji z tej samej minuty. W Nginx często pojawiają się komunikaty wskazujące na odmowę połączenia, przedwczesne zamknięcie połączenia przez upstream albo problem z rozwiązaniem nazwy. Każdy z nich prowadzi diagnostykę w innym kierunku.

Brak jakiegokolwiek wpisu po stronie aplikacji sugeruje, że żądanie do niej nie dotarło. Trzeba wtedy sprawdzić adres, port, DNS, reguły sieciowe i stan procesu. Jeśli aplikacja zarejestrowała wyjątek, zakończenie procesu albo utratę połączenia z bazą, to właśnie ta informacja jest ważniejsza niż ogólny komunikat 502 pokazany użytkownikowi.

W środowisku z wieloma instancjami zapisuj identyfikator hosta lub kontenera. Bez niego seria błędów może wyglądać losowo, chociaż w rzeczywistości wszystkie pochodzą z jednego niesprawnego węzła.

Przetestuj serwer nadrzędny bez pośredników

Jeśli masz dostęp do serwera, z którego reverse proxy łączy się z aplikacją, wykonaj test bezpośrednio z tego miejsca. Dla lokalnej usługi może wyglądać tak:

curl -i http://127.0.0.1:3000/health

Adres i port muszą odpowiadać rzeczywistej konfiguracji. Poprawna odpowiedź z własnego komputera nie wystarczy, jeżeli proxy działa w innym kontenerze, sieci lub centrum danych. Test powinien odtworzyć trasę, której używa warstwa pośrednia.

Jeśli endpoint kondycji odpowiada, a zwykła podstrona nie, sprawdź zależności uruchamiane dopiero podczas obsługi żądania: bazę danych, pamięć podręczną, kolejkę i zewnętrzne API. Prosty test health powinien być szybki, ale warto mieć również oddzielny test gotowości, który potwierdza, że instancja może bezpiecznie przyjąć ruch.

Zweryfikuj zasoby i stabilność procesu

Proces aplikacji może uruchamiać się poprawnie, a po chwili znikać. Sprawdź zużycie pamięci i procesora, wolne miejsce na dysku, liczbę otwartych połączeń oraz komunikaty systemowe. Szczególną uwagę zwróć na cykliczne restarty kontenera i zdarzenia informujące o zakończeniu procesu z powodu braku pamięci.

Jeżeli problem występuje tylko przy większym ruchu, obserwuj limity połączeń i pulę połączeń do bazy. Samo zwiększenie timeoutu może jedynie wydłużyć oczekiwanie użytkownika, jeśli prawdziwą przyczyną jest zakleszczenie lub zapytanie przeciążające bazę. Najpierw ustal, na co aplikacja czeka, a dopiero potem zmieniaj limity.

Warto także sprawdzić miejsce przeznaczone na logi i pliki tymczasowe. Zapełniony dysk potrafi uniemożliwić zapis sesji, utworzenie pliku lub poprawny start usługi, mimo że sam serwer nadal odpowiada na podstawowe polecenia.

CDN, zapora i certyfikat źródłowy

Gdy przed stroną działa CDN, kod 502 może oznaczać, że jego węzeł nie potrafi połączyć się z serwerem źródłowym. Sprawdź, czy rekord wskazuje właściwy adres, port jest dostępny, a zapora zezwala na ruch z aktualnych zakresów używanych przez usługę. Blokada może objąć tylko część węzłów, dlatego awaria bywa zależna od lokalizacji użytkownika.

Jeśli CDN łączy się ze źródłem przez HTTPS, certyfikat musi pasować do nazwy, być ważny i mieć poprawny łańcuch. Certyfikat widoczny dla użytkownika może być prawidłowy, podczas gdy osobny certyfikat na połączeniu CDN–serwer źródłowy jest nieważny. W takiej sytuacji warto wykonać test certyfikatu strony i osobno zweryfikować konfigurację originu.

Nie wyłączaj na stałe weryfikacji TLS tylko po to, aby błąd zniknął. To może przywrócić dostępność, ale osłabia ochronę połączenia i ukrywa właściwą przyczynę problemu.

Błąd 502 w WordPressie

W WordPressie źródłem błędu bywa zatrzymany proces PHP-FPM, brak wolnych workerów, przekroczony limit pamięci albo wtyczka, która wykonuje bardzo długie zapytanie. Problem może pojawić się po aktualizacji, zmianie wersji PHP, imporcie dużej liczby danych lub uruchomieniu zadania cyklicznego.

Sprawdź log PHP, log serwera WWW i stan puli PHP-FPM. Jeżeli awaria zaczęła się bezpośrednio po aktualizacji, przywróć ostatnią działającą wersję zgodnie z przygotowaną procedurą. Nie edytuj losowo plików działającej strony bez kopii. Szerszą kolejność działań opisuje poradnik jak naprawić stronę na WordPressie.

Przy powtarzającym się problemie sprawdź, czy harmonogram zadań nie uruchamia kosztownej operacji o tej samej godzinie. Sam restart PHP może chwilowo pomóc, ale bez poznania przyczyny błąd wróci przy kolejnym wzroście obciążenia.

Jak bezpiecznie reagować podczas awarii?

Najpierw ogranicz wpływ problemu. Jeśli jedna instancja jest niesprawna, wyłącz ją z load balancera. Jeżeli błąd rozpoczął się po wdrożeniu i istnieje sprawdzona procedura wycofania, powrót do poprzedniej wersji może być bezpieczniejszy niż poprawianie produkcji pod presją czasu. Dla planowanej przerwy lepiej pokazać kontrolowany komunikat 503 niż przypadkowy 502.

Zapisuj wykonane działania i godziny. Kilka osób zmieniających jednocześnie DNS, proxy i aplikację może utrudnić znalezienie przyczyny oraz bezpieczne cofnięcie zmian. Po każdym kroku wykonaj ten sam test, aby wiedzieć, co rzeczywiście przywróciło działanie.

Po naprawie sprawdź nie tylko stronę główną. Przetestuj logowanie, formularze, wyszukiwarkę, koszyk lub inne kluczowe funkcje. Potwierdź też, że wszystkie instancje są zdrowe i ponownie włączone do obsługi ruchu.

Jak zapobiegać kolejnym błędom 502?

Nie każdej awarii da się uniknąć, ale można skrócić czas jej wykrycia i ograniczyć zasięg. Podstawą jest monitoring obejmujący nie tylko kod strony głównej, lecz także kluczowe procesy. Warto mierzyć czas odpowiedzi, liczbę błędów 5xx, dostępność instancji, wykorzystanie pamięci oraz stan połączeń z bazą.

Dodaj testy gotowości i ustaw load balancer tak, aby nie kierował ruchu do aplikacji przed zakończeniem jej startu. Podczas wdrożeń stopniowo włączaj nowe instancje i automatycznie zatrzymuj publikację, gdy rośnie liczba błędów. Utrzymuj też kopię poprzedniej wersji i prostą procedurę wycofania.

Przydatne są alerty oparte na kilku kolejnych niepowodzeniach albo odsetku błędnych odpowiedzi. Pojedynczy błąd może być krótkim zakłóceniem, ale seria 502 wymaga szybkiej reakcji. Więcej wskazówek znajdziesz w artykule o monitoringu dostępności strony.

Lista kontrolna dla administratora

Gdy strona zwraca 502 Bad Gateway, wykonaj kolejno następujące czynności:

1. Zapisz godzinę, adres i identyfikator błędnego żądania.
2. Sprawdź, czy awaria dotyczy wszystkich podstron, lokalizacji i instancji.
3. Porównaj czas zdarzenia z ostatnimi wdrożeniami i zmianami konfiguracji.
4. Odczytaj log błędów proxy oraz log aplikacji z tego samego przedziału czasu.
5. Sprawdź, czy proces działa i nasłuchuje na właściwym adresie oraz porcie.
6. Przetestuj endpoint aplikacji bezpośrednio z hosta lub sieci używanej przez proxy.
7. Zweryfikuj pamięć, procesor, dysk, limity połączeń i zależności aplikacji.
8. Sprawdź DNS, zaporę i certyfikat na połączeniu z serwerem źródłowym.
9. Jeśli przyczyną jest wdrożenie, rozważ kontrolowany powrót do ostatniej działającej wersji.
10. Po naprawie przetestuj kluczowe funkcje i uzupełnij monitoring o sygnał, którego zabrakło.

Podsumowanie

Błąd 502 Bad Gateway oznacza, że warstwa pośrednia nie uzyskała prawidłowej odpowiedzi od kolejnego serwera. Użytkownik może sprawdzić stronę w innej sieci i potwierdzić zakres problemu, ale trwała naprawa zwykle leży po stronie właściciela serwisu.

Administrator powinien zacząć od ustalenia czasu i zakresu awarii, a następnie zestawić logi proxy z logami aplikacji. Bezpośredni test upstreamu, kontrola procesu, zasobów, DNS, zapory i TLS pozwalają szybko zawęzić przyczynę. Po przywróceniu działania warto poprawić monitoring, testy gotowości i procedurę wdrożenia, aby kolejny incydent został wykryty wcześniej i nie objął całego ruchu.