Kod 502 pojawia się, gdy serwer działający jako brama lub proxy nie dostał prawidłowej odpowiedzi od usługi znajdującej się dalej. W typowym WordPressie na Nginx „upstreamem” jest PHP-FPM. To dlatego przy 502 grzebanie w ustawieniach permalinks albo ponowna instalacja WordPressa zwykle nie jest pierwszym krokiem. Najpierw trzeba sprawdzić, czy proces PHP działa i czy serwer WWW potrafi się z nim komunikować.
Szybka odpowiedź
Sprawdź error log Nginx dokładnie z chwili błędu. Komunikaty typu connect() failed, connection refused, no such file or directory lub upstream prematurely closed connection prowadzą do różnych przyczyn. Następnie sprawdź status PHP-FPM, socket/port, liczbę workerów i log samego PHP. Dopiero gdy upstream działa, wracaj do aplikacji.
Socket czy port TCP?
Nginx może przekazywać żądania PHP przez socket unixowy albo port TCP. Jeśli po aktualizacji PHP zmieniła się nazwa socketu, a konfiguracja vhosta nadal wskazuje starą ścieżkę, Nginx nie połączy się z PHP-FPM. Podobny efekt da zatrzymana usługa albo błędny port. To czysta warstwa serwerowa — WordPress nie zdąży się uruchomić.
PHP-FPM może działać, ale nie wyrabiać
Usługa widoczna jako „active” nie gwarantuje, że ma wolne workery. Przy zbyt małej puli, ciężkich żądaniach albo wycieku pamięci kolejka rośnie, a procesy mogą być ubijane. Sprawdź log FPM, pamięć, max_children, czas trwania żądań i ewentualne restarty OOM. Zwiększenie liczby procesów bez sprawdzenia RAM-u może pogorszyć sytuację.
Dlaczego 502 bywa chwilowy
Restart PHP, deploy, rotacja konfiguracji albo krótki skok obciążenia mogą dać kilka błędów 502 i po chwili wszystko wraca. Jeśli monitoring pokazuje powtarzalny wzorzec, nie uznawaj problemu za rozwiązany tylko dlatego, że strona znowu się otwiera. Trzeba znaleźć przyczynę restartów lub przeciążenia.
CDN może pokazać własną stronę 502
Jeśli przed serwerem działa CDN lub proxy, błąd może zostać wygenerowany właśnie tam. Porównaj odpowiedź z originem, nagłówki i logi obu warstw. Dzięki temu wiesz, czy problem leży między użytkownikiem a CDN, CDN a originem, czy Nginx a PHP-FPM.
Kiedy WordPress jednak ma związek
Ciężka wtyczka, import, generowanie obrazu lub zapytanie do zewnętrznego API może doprowadzić proces PHP do awarii lub wyczerpania zasobów. WordPress może więc być źródłem obciążenia, ale sam kod 502 nadal opisuje problem komunikacji między warstwami. Szukaj pełnego łańcucha: żądanie → Nginx → PHP-FPM → WordPress → baza/usługi zewnętrzne.
Jak potwierdzić, że naprawa naprawdę działa?
Po przywróceniu komunikacji Nginx↔PHP-FPM sprawdź nie tylko status usługi, ale też rzeczywisty request PHP. Otwórz kilka dynamicznych podstron i panel administracyjny, a następnie zobacz, czy w error logu nie ma nowych komunikatów upstream prematurely closed connection, connection refused lub restartów workerów. Jeżeli 502 występował podczas większego ruchu, wykonaj kontrolowany test kilku równoległych żądań zamiast uznawać pojedynczy reload za dowód stabilności.
Co obserwować po zmianie?
Przy problemach z pulą PHP warto obserwować zajętość workerów, pamięć procesu, długość kolejki i liczbę restartów przez kilka godzin. Jeżeli serwer był ubijany przez OOM, sama zmiana pm.max_children bez policzenia RAM-u może przesunąć problem na inne usługi, np. bazę. Po naprawie trend zasobów powinien być przewidywalny również podczas crona, backupu i importów.
Kiedy przekazać temat dalej?
Eskaluj, gdy 502 dotyczy kilku witryn na tym samym serwerze, pojawia się po restartach systemu albo log wskazuje na socket/serwis, którego konfiguracją nie zarządzasz. W takim przypadku problem jest szerszy niż pojedyncza instalacja WordPressa i wymaga administracji infrastruktury, nie kolejnej modyfikacji CMS.
Praktyczny scenariusz diagnostyczny
Przykład z hostingu: po zwiększonym ruchu Nginx zaczyna zwracać 502, a po restarcie PHP-FPM strona znów działa. Restart przywrócił usługę, ale nie usunął przyczyny. Sprawdź logi z minut poprzedzających awarię: liczbę zajętych workerów, komunikaty o ubijaniu procesów, pamięć, czas wykonywania skryptów i ciężkie requesty. Jeżeli problem wywołuje import lub zadanie cron, przenieś je poza szczyt, zoptymalizuj operację albo ogranicz współbieżność. Jeżeli pula PHP jest zbyt mała w stosunku do realnego ruchu, dopiero wtedy strojenie konfiguracji ma sens. Po zmianie obserwuj kolejny okres obciążenia. Stabilna praca przez kilka minut po restarcie nie jest testem — testem jest przejście przez ten sam warunek, który wcześniej wywołał 502.
Bezpieczna kolejność działań
- Sprawdź error log Nginx/proxy z czasu błędu.
- Zweryfikuj status PHP-FPM i poprawność socketu lub portu.
- Sprawdź restarty, OOM, liczbę zajętych workerów i pamięć.
- Jeśli błąd jest okresowy, porównaj go z cronem, importem i ruchem.
- Dopiero potem analizuj konkretną wtyczkę lub kod WordPressa.
- Po zmianach obserwuj 5xx i czasy odpowiedzi przez monitoring.
Czego nie robić
Nie restartuj usług w kółko bez zapisania logów — restart może skasować najprostszy do uchwycenia objaw. Nie zwiększaj bez końca liczby workerów PHP na serwerze, który nie ma wystarczającej pamięci.
Powiązane poradniki HeatLogic
Potrzebujesz pomocy?
Przy 502 HeatLogic może sprawdzić cały tor żądania: proxy, Nginx, PHP-FPM, logi aplikacji i zasoby serwera. To pozwala usunąć przyczynę zamiast tylko cyklicznie restartować PHP.
Źródła techniczne
Najczęściej zadawane pytania
Czy 502 oznacza awarię bazy danych?
Nie bezpośrednio. Baza może pośrednio doprowadzić do problemu z procesem PHP, ale 502 opisuje nieprawidłową odpowiedź upstreamu.
Czy restart PHP-FPM może pomóc?
Może chwilowo przywrócić działanie, ale bez analizy logów nie wiadomo, dlaczego usługa przestała odpowiadać.
Czy 502 i 504 to to samo?
Nie. 502 oznacza nieprawidłową odpowiedź upstreamu, a 504 zwykle przekroczenie czasu oczekiwania na odpowiedź.
Czy winna może być wtyczka?
Tak pośrednio, jeśli powoduje awarię lub skrajne obciążenie PHP, ale trzeba to potwierdzić w logach.