Błąd 502 Bad Gateway w WordPressie — jak znaleźć przyczynę

502 Bad Gateway oznacza, że serwer działający jako gateway lub proxy otrzymał nieprawidłową odpowiedź od upstreamu, z którym komunikował się podczas obsługi żądania. W WordPressie takim upstreamem może być między innymi PHP-FPM, Apache działający za NGINX-em albo inna warstwa aplikacyjna hostingu.

Dlatego 502 nie należy diagnozować wyłącznie jako „błędu WordPressa”. Strona może mieć poprawną bazę i pliki, a problem wystąpić pomiędzy warstwą frontową serwera a procesem, który ma wygenerować odpowiedź PHP.

Przy 502 najpierw ustal, kto zwrócił błąd i z jakim upstreamem próbował się połączyć. Dopiero potem szukaj przyczyny w PHP, WordPressie albo zasobach hostingu.

Co właściwie oznacza 502 Bad Gateway?

Kod 502 jest odpowiedzią serwera pośredniczącego. Gateway lub proxy otrzymał od upstreamu odpowiedź, której nie mógł poprawnie użyć do obsługi żądania.

W typowym środowisku hostingowym przepływ może wyglądać tak:

przeglądarka
    ↓
NGINX / reverse proxy
    ↓
Apache lub PHP-FPM
    ↓
WordPress
    ↓
MariaDB / MySQL

Jeżeli problem wystąpi pomiędzy NGINX-em a PHP-FPM, użytkownik może zobaczyć 502, choć WordPress nie zdąży nawet wygenerować własnej strony błędu.

Objaw	Pierwszy trop
502 pojawia się na całej witrynie	PHP-FPM, backend, reverse proxy albo awaria usługi
502 dotyczy tylko ciężkiej operacji	Reset/zerwanie połączenia z upstreamem, błąd procesu albo niestabilność pod obciążeniem
Po odświeżeniu strona czasem działa	Niestabilny upstream, restart procesu albo okresowa niedostępność backendu
502 pojawiło się po zmianie PHP	Socket/port PHP-FPM, konfiguracja puli lub niedziałająca usługa
502 występuje za CDN, ale origin odpowiada poprawnie	Połączenie CDN → origin lub konfiguracja proxy

502, 503 i 504 to trzy różne sytuacje

W praktyce błędy te często są wrzucane do jednego worka, ale ich znaczenie jest inne.

502 Bad Gateway — gateway lub proxy dostał nieprawidłową odpowiedź od upstreamu.
503 Service Unavailable — serwer jest chwilowo niezdolny do obsługi żądania, np. z powodu przeciążenia lub prac serwisowych.
504 Gateway Timeout — gateway lub proxy nie otrzymał odpowiedzi od upstreamu w wymaganym czasie.

To rozróżnienie pomaga ustalić kierunek diagnozy. Przy 504 naturalnym tropem jest czas oczekiwania. Przy 502 trzeba przede wszystkim sprawdzić, czy upstream działa i czy odpowiedź pomiędzy warstwami jest prawidłowa.

Gdy upstreamem jest PHP-FPM

PHP-FPM nie działa albo serwer wskazuje zły endpoint

W wielu konfiguracjach NGINX lub Apache przekazuje pliki PHP do PHP-FPM. Komunikacja może odbywać się przez socket Unix albo port TCP.

502 może pojawić się, gdy:

PHP-FPM nie działa,
proces został zatrzymany lub zrestartowany,
serwer WWW próbuje użyć nieistniejącego socketu,
konfiguracja wskazuje niewłaściwy port,
socket istnieje, ale serwer nie ma do niego właściwego dostępu,
backend resetuje lub zamyka połączenie przed zwróceniem poprawnej odpowiedzi.

Szczególnie po zmianie wersji PHP warto sprawdzić, czy vhost nadal wskazuje właściwą pulę PHP-FPM. Samo zainstalowanie nowej wersji PHP nie gwarantuje, że routing FastCGI został przełączony poprawnie.

Backend działa, ale jest niestabilny pod obciążeniem

Przeciążenie może pośrednio doprowadzić do 502, jeśli backend zaczyna odrzucać lub resetować połączenia, procesy są ubijane albo usługa staje się okresowo niedostępna.

Sam fakt, że wszystkie workery PHP są zajęte, nie przesądza jednak o 502. Limit pm.max_children określa liczbę jednocześnie obsługiwanych żądań, a kolejne mogą oczekiwać w kolejce. Jeśli oczekiwanie trwa zbyt długo, problem może objawić się timeoutem, w tym 504 na warstwie proxy.

Dlatego przy błędzie pojawiającym się pod obciążeniem sprawdź równolegle:

użycie CPU i pamięci,
liczbę aktywnych procesów lub workerów PHP,
limity konta hostingowego,
logi PHP-FPM i serwera,
czas oraz rodzaj operacji wywołującej błąd.

Jeżeli błąd pojawia się głównie przy imporcie, eksporcie, generowaniu raportu albo innym ciężkim zadaniu, ważny jest również profil samej operacji.

Do sprawdzenia warstwy zasobowej można użyć Diagnostyki zasobów hostingu.

PHP kończy request przed poprawną odpowiedzią

W prostszej konfiguracji fatal error PHP może dać bezpośrednio 500. W środowisku z proxy rezultat widoczny dla użytkownika zależy również od tego, co stanie się z połączeniem pomiędzy backendem a gatewayem.

Jeżeli proces PHP zakończy się lub zresetuje połączenie w sposób, który uniemożliwia proxy odebranie poprawnej odpowiedzi, warstwa frontowa może zwrócić 502.

Dlatego przy świeżo zainstalowanym pluginie, aktualizacji motywu albo zmianie wersji PHP warto sprawdzić także log PHP, nawet jeśli przeglądarka nie pokazuje kodu 500. Nie oznacza to jednak, że każdy 502 jest fatal errorem WordPressa — potrzebny jest dowód w logach.

CDN lub reverse proxy może zwrócić własny 502

Jeżeli witryna działa przez reverse proxy lub CDN, pojawia się jeszcze jedna warstwa komunikacji:

użytkownik → CDN/proxy → origin → PHP/WordPress

Błąd widoczny dla użytkownika może więc pochodzić z originu albo zostać wygenerowany przez warstwę CDN/proxy na podstawie problemu w komunikacji z originem.

Przy takim układzie warto porównać:

odpowiedź publicznej domeny przez proxy,
odpowiedź originu, jeśli można ją bezpiecznie sprawdzić bez omijania zabezpieczeń,
logi CDN/proxy,
logi serwera źródłowego z tego samego czasu.

W przypadku Cloudflare dokumentacja rozróżnia 502/504 pochodzące z originu od błędów generowanych przez samo Cloudflare. Jeśli operator udostępnia dodatkowe pola diagnostyczne, warto wykorzystać je do ustalenia źródła odpowiedzi.

Nie wyłączaj jednak ochrony CDN lub proxy w ciemno na produkcji tylko po to, aby wykonać test. Najpierw wykorzystaj dostępne logi i narzędzia diagnostyczne operatora.

Zabezpiecz dane diagnostyczne zanim usuniesz objaw

Jeżeli 502 powstaje przed wykonaniem aplikacji, debug.log WordPressa może pozostać pusty. Wtedy ważniejsze są logi NGINX-a, Apache, PHP-FPM albo panelu hostingowego.

W logach można szukać między innymi informacji o:

braku połączenia z upstreamem,
odrzuconym połączeniu,
zamknięciu lub resecie połączenia przez backend,
nieistniejącym sockecie,
błędzie uprawnień do socketu,
nieprawidłowym nagłówku lub odpowiedzi FastCGI.

Jeżeli log serwera wskazuje konkretny upstream, wiadomo już, której warstwy dotyczy awaria. To znacznie lepszy punkt wyjścia niż wyłączanie losowych pluginów.

Przy sporadycznych 502 zanotuj również dokładną godzinę z uwzględnieniem strefy czasowej, URL, wykonywaną operację, zakres awarii oraz to, czy kolejne odświeżenie zadziałało. Takie dane można potem zestawić z logami proxy, PHP-FPM i wykorzystaniem zasobów.

Restart PHP-FPM lub procesów konta może chwilowo przywrócić działanie strony, ale jednocześnie usuwa część bieżącego stanu potrzebnego do diagnozy. Jeżeli sytuacja na to pozwala, przed restartem zapisz fragmenty logów, stan procesów i wykorzystanie zasobów.

Jeżeli serwis produkcyjny jest całkowicie niedostępny, przywrócenie działania może mieć wyższy priorytet. Po restarcie warto jednak wrócić do logów historycznych i ustalić, dlaczego backend przestał odpowiadać poprawnie.

Przy analizie logów pomocny jest poradnik o error_log i debug.log w WordPressie.

Bezpieczna procedura diagnozy 502 w WordPressie

Zapisz dokładny URL, godzinę i okoliczności wystąpienia 502.
Ustal, która warstwa zwraca błąd: CDN, NGINX, Apache czy inny gateway.
Sprawdź log tej warstwy z czasu błędu.
Zidentyfikuj upstream, do którego gateway próbował się połączyć.
Jeżeli upstreamem jest PHP-FPM, sprawdź usługę, pulę, socket lub port.
Po zmianie PHP potwierdź, że serwer wskazuje właściwy backend.
Sprawdź log PHP i WordPressa pod kątem błędu aplikacji.
Jeżeli problem pojawia się pod obciążeniem, odróżnij kolejkę/timeout od odrzucenia lub resetu połączenia.
Przy CDN porównaj zdarzenie z logami originu.
Restart wykonuj świadomie — najlepiej po zabezpieczeniu danych diagnostycznych.

Jeżeli witryna nie zwraca 502, lecz przede wszystkim działa bardzo wolno, zacznij od poradnika WordPress działa wolno — hosting czy strona?.

Najważniejsze wnioski

502 jest błędem gatewaya/proxy komunikującego się z upstreamem;
w środowisku WordPress upstreamem może być PHP-FPM, Apache albo inna warstwa backendowa;
502 nie jest tym samym co 503 ani 504;
po zmianie PHP trzeba sprawdzić również konfigurację socketu lub portu backendu;
zajęte workery nie oznaczają automatycznie 502 — mogą powodować również kolejkowanie i timeout;
bardziej bezpośrednimi tropami 502 są odrzucenie, reset połączenia, niedostępny backend albo nieprawidłowa odpowiedź;
przy 502 log proxy może być ważniejszy niż debug.log WordPressa;
błąd PHP może pośrednio skończyć się 502, ale wymaga potwierdzenia w logach;
przy sporadycznych awariach dokładny czas zdarzenia jest kluczowy dla korelacji logów;
restart może przywrócić usługę, ale nie zastępuje ustalenia przyczyny.

Źródła

RFC 9110 — 502 Bad Gateway — definicja kodu 502.
RFC 9110 — 503 Service Unavailable — rozróżnienie 503.
RFC 9110 — 504 Gateway Timeout — rozróżnienie 504.
NGINX — ngx_http_proxy_module — komunikacja reverse proxy z upstreamem.
NGINX — ngx_http_fastcgi_module — FastCGI, błędy, timeouty i nieprawidłowe odpowiedzi upstreamu.
PHP Manual — FastCGI Process Manager — PHP-FPM jako backend FastCGI.
PHP Manual — FPM configuration — pm.max_children, listen/socket i konfiguracja puli.
Cloudflare — Error 502 or 504 — rozróżnienie błędów originu i błędów generowanych przez Cloudflare.
WordPress Developer Resources — Debugging in WordPress — logowanie błędów aplikacji.