Błąd 504 Gateway Timeout w WordPressie — co powoduje timeout i jak go diagnozować?

504 Gateway Timeout oznacza, że serwer działający jako gateway lub proxy nie otrzymał na czas odpowiedzi od upstreamu potrzebnej do obsługi żądania. W WordPressie upstreamem może być PHP-FPM, Apache działający za NGINX-em, aplikacja za reverse proxy albo origin widziany przez CDN.

To odróżnia 504 od 502. Przy 502 problemem jest nieprawidłowa odpowiedź upstreamu; przy 504 kluczowy jest czas oczekiwania.

Przy 504 nie zaczynaj od podnoszenia timeoutów. Najpierw sprawdź, na co gateway czekał i dlaczego odpowiedź trwała tak długo.

Co właściwie oznacza 504 Gateway Timeout?

W środowisku WordPressa przepływ żądania może wyglądać tak:

przeglądarka
    ↓
CDN / reverse proxy / NGINX
    ↓
Apache lub PHP-FPM
    ↓
WordPress
    ↓
MySQL / zewnętrzne API

Jeżeli jedna z wcześniejszych warstw czeka na odpowiedź kolejnej i nie otrzyma jej w wymaganym czasie, może zakończyć żądanie kodem 504.

Objaw	Pierwszy trop
504 tylko przy imporcie, eksporcie lub generowaniu raportu	Długa operacja PHP, baza danych albo zewnętrzne API
504 pojawia się przy dużym ruchu	Kolejka requestów, zajęte workery, baza lub przeciążony upstream
504 zaczęło się po zmianie proxy/CDN	Timeout warstwy pośredniej i komunikacja z originem
Po odświeżeniu lekka strona działa, ciężka znów kończy się 504	Problem zależny od czasu wykonania konkretnego requestu
504 występuje okresowo także na prostych stronach	Niestabilność backendu, bazy lub zasobów hostingu

Najpierw odróżnij 504 od 502 i 503

• 502 Bad Gateway — gateway otrzymał od upstreamu odpowiedź, której nie mógł poprawnie użyć.
• 503 Service Unavailable — usługa jest chwilowo niezdolna do obsługi żądania.
• 504 Gateway Timeout — gateway nie otrzymał potrzebnej odpowiedzi upstreamu w wymaganym czasie.

To ważne diagnostycznie. Przy 504 backend może nadal działać — tylko zbyt wolno względem limitu oczekiwania warstwy stojącej przed nim.

Jeżeli zamiast timeoutu widzisz przerwane albo nieprawidłowe połączenie z backendem, właściwszym punktem odniesienia jest poradnik o błędzie 502 Bad Gateway.

Gdzie request naprawdę spędza czas?

Kod PHP i ciężka operacja

504 często wychodzi przy operacjach, które wykonują znacznie więcej pracy niż zwykłe wyświetlenie strony. Przykładami są import dużego pliku, eksport danych, generowanie PDF lub raportu, masowa zmiana produktów czy tworzenie kopii wykonywanej w jednym żądaniu HTTP.

Najważniejsze pytanie brzmi wtedy nie „jaki timeout zwiększyć?”, lecz co wykonywał backend przez cały ten czas.

Jeżeli ta sama strona działa normalnie bez konkretnej operacji, problem prawdopodobnie nie dotyczy całej instalacji WordPressa. Trzeba zawęzić diagnozę do kodu uruchamianego w wolnym requestcie.

Baza danych

Request WordPressa może pozostawać aktywny dlatego, że czeka na zakończenie zapytania SQL albo zwolnienie zasobu w bazie.

Przy 504 warto sprawdzić, czy w czasie problemu występują:

• długie zapytania,
• duża liczba równoległych połączeń,
• blokady lub długie transakcje,
• operacje na bardzo dużych tabelach,
• nieefektywne zapytania wykonywane przez plugin.

Jeżeli timeout występuje tylko w jednym raporcie, wyszukiwaniu albo operacji WooCommerce, taki trop jest silniejszy niż globalna awaria serwera.

Nie należy jednak wnioskować o problemie bazy wyłącznie z kodu 504. Potrzebne są logi, profiling albo dane z monitoringu pokazujące, gdzie request faktycznie spędza czas.

Zewnętrzne API

Nie każdy długi request wykonuje pracę lokalnie. Plugin może w trakcie generowania strony czekać na API operatora płatności, system ERP, zewnętrzny feed, serwer licencyjny, system kurierski albo inny endpoint HTTP.

Jeżeli zewnętrzny serwis odpowiada wolno albo wcale, proces PHP może pozostać zajęty przez cały czas oczekiwania.

Dlatego w logach warto szukać nie tylko błędów PHP, ale także informacji o requestach wychodzących i czasie ich wykonania. Szczególnie podejrzany jest przypadek, w którym 504 pojawia się wyłącznie podczas operacji korzystającej z jednej konkretnej integracji.

Zajęte workery mogą wydłużyć oczekiwanie, ale trzeba sprawdzić gdzie powstaje kolejka

PHP-FPM ma ograniczoną liczbę procesów mogących równocześnie obsługiwać żądania. Jeżeli wszystkie są zajęte, kolejne requesty mogą oczekiwać na możliwość wykonania.

To może prowadzić do sytuacji, w której sam kod PHP nie potrzebuje kilkudziesięciu sekund, ale żądanie spędza znaczną część czasu w kolejce przed rozpoczęciem wykonania.

Dlatego przy 504 pod obciążeniem warto zestawić:

• liczbę aktywnych workerów,
• limit pm.max_children,
• ruch w momencie awarii,
• czas odpowiedzi PHP,
• timeout warstwy proxy.

Samo zwiększenie liczby workerów również nie jest automatycznym rozwiązaniem. Każdy proces zużywa pamięć i CPU, więc zbyt agresywna konfiguracja może przenieść problem na inną warstwę.

Szerzej limity PHP opisuje poradnik o PHP workers na hostingu WordPress.

Najpierw znajdź timeout, który rzeczywiście zadziałał

W jednej ścieżce requestu może działać kilka niezależnych limitów czasu. Osobny timeout może mieć CDN, reverse proxy, NGINX komunikujący się z FastCGI, Apache lub inny backend, kod PHP czy klient HTTP używany do zewnętrznego API.

W NGINX proxy_read_timeout i fastcgi_read_timeout nie są prostym maksymalnym czasem całego requestu. Określają czas pomiędzy kolejnymi operacjami odczytu danych z upstreamu lub FastCGI. Domyślna wartość obu dyrektyw wynosi 60 sekund.

Przykładowo NGINX może czekać do 60 sekund pomiędzy kolejnymi odczytami danych z upstreamu lub FastCGI. Jeżeli backend przez ten okres niczego nie zwróci, połączenie może zostać zamknięte i użytkownik zobaczy błąd timeout. Nie oznacza to jednak, że każdy request trwający ponad 60 sekund automatycznie zakończy się błędem — sposób liczenia limitu zależy od konkretnej warstwy i dyrektywy.

Dlatego przed zmianą konfiguracji ustal który limit został przekroczony. Podniesienie timeoutu na jednej warstwie może tylko przesunąć awarię do następnej.

Kiedy zwiększenie timeoutu ma sens?

Nie każda długa operacja jest błędem. Eksport tysięcy rekordów albo generowanie rozbudowanego raportu może rzeczywiście potrzebować więcej czasu niż zwykły request strony.

Zwiększenie odpowiedniego timeoutu może być uzasadnione, jeśli:

• operacja ma być wykonywana synchronicznie,
• znany jest jej rzeczywisty czas działania,
• zasoby serwera pozwalają ją bezpiecznie wykonywać,
• nie ma lepszego modelu wykonania poza requestem HTTP.

Jeżeli jednak pojedyncze wyświetlenie produktu zaczęło nagle trwać minutę, samo zwiększenie timeoutu jest słabą naprawą. Lepiej znaleźć zapytanie, integrację albo fragment kodu, który spowodował regresję.

Długie zadania często lepiej wykonywać asynchronicznie lub z użyciem kolejki/cron zamiast utrzymywać otwarte żądanie użytkownika przez wiele minut.

CDN może zakończyć oczekiwanie wcześniej niż origin

Przy CDN lub zewnętrznym reverse proxy użytkownik nie komunikuje się bezpośrednio z serwerem WordPressa.

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

Warstwa edge ma własne zasady i limity czasu. Możliwa jest więc sytuacja, w której origin nadal wykonuje operację, ale połączenie od strony użytkownika zostało już zakończone błędem timeout.

Nie każdy CDN sygnalizuje przekroczenie swojego limitu właśnie kodem 504 — operator może używać także własnych kodów błędów, dlatego trzeba sprawdzić dokumentację i logi konkretnej warstwy.

Przy diagnozie porównaj dane z proxy/CDN i originu dla tego samego requestu oraz czasu zdarzenia. Jeżeli operator rozróżnia kod wygenerowany na edge od statusu otrzymanego z originu, takie informacje mogą szybko wskazać warstwę problemu.

Nie zakładaj też, że zwiększenie limitu PHP zmieni timeout kontrolowany przez zewnętrzny CDN.

Zbierz czas i logi zanim zaczniesz zmieniać limity

Przy 504 szczególnie ważna jest korelacja czasu. Zanotuj:

• dokładny timestamp,
• URL,
• rodzaj wykonywanej operacji,
• czas od rozpoczęcia requestu do błędu,
• czy ten czas powtarza się podobnie przy kolejnych próbach.

Jeżeli 504 pojawia się niemal zawsze po podobnym czasie — np. około 30, 60 czy 120 sekund — jest to mocny sygnał, że warto poszukać konkretnego limitu czasowego na jednej z warstw.

Potem zestaw zdarzenie z logami proxy, PHP-FPM, PHP i aplikacji. Jeżeli WordPress nie zdążył wygenerować odpowiedzi, sam debug.log może nie wyjaśnić całego problemu.

Przy pracy z logami pomocny jest poradnik o error_log i debug.log w WordPressie.

Bezpieczna procedura diagnozy 504

1. Zapisz dokładny URL, godzinę i czas do wystąpienia timeoutu.
2. Ustal, która warstwa zwróciła błąd timeout.
3. Sprawdź, na jaki upstream ta warstwa czekała.
4. Porównaj zdarzenie z logami proxy, PHP-FPM, PHP i aplikacji.
5. Jeżeli problem dotyczy ciężkiej operacji, ustal gdzie request spędza czas.
6. Przy dużym ruchu sprawdź kolejkę i wykorzystanie workerów PHP.
7. Zweryfikuj bazę danych pod kątem długich zapytań i oczekiwania.
8. Sprawdź zewnętrzne API używane przez problematyczną operację.
9. Ustal konkretny timeout, który został przekroczony, zanim zwiększysz jego wartość.
10. Jeżeli zadanie jest z natury długie, rozważ przeniesienie go poza synchroniczny request HTTP.

Jeżeli równocześnie widzisz wysokie wykorzystanie procesów, CPU lub pamięci, pomocna będzie Diagnostyka zasobów hostingu.

Najważniejsze wnioski

• 504 oznacza przekroczenie czasu oczekiwania gatewaya na upstream;
• backend może nadal działać, mimo że użytkownik otrzymał już błąd;
• 502, 503 i 504 wymagają innego kierunku diagnozy;
• zajęte workery mogą zwiększać czas oczekiwania przez kolejkę;
• PHP może czekać na bazę danych albo zewnętrzne API;
• w jednym requeście może działać kilka niezależnych timeoutów;
• proxy_read_timeout i fastcgi_read_timeout w NGINX dotyczą przerw między odczytami, a nie prostego limitu całkowitego czasu requestu;
• CDN może sygnalizować własny timeout innym kodem niż 504;
• zwiększenie timeoutu ma sens dopiero po ustaleniu, który limit został przekroczony i dlaczego;
• powtarzalny czas do błędu jest ważną wskazówką diagnostyczną;
• długie zadania często lepiej wykonywać poza synchronicznym requestem HTTP.

Źródła

1. RFC 9110 — 504 Gateway Timeout — definicja kodu 504.
2. RFC 9110 — 502 Bad Gateway — rozróżnienie 502.
3. RFC 9110 — 503 Service Unavailable — rozróżnienie 503.
4. NGINX — proxy_read_timeout — czas pomiędzy kolejnymi odczytami danych z proxied server.
5. NGINX — fastcgi_read_timeout — czas pomiędzy kolejnymi odczytami danych z FastCGI.
6. PHP Manual — FPM configuration — pm.max_children, listen queue i konfiguracja PHP-FPM.
7. WordPress Developer Resources — HTTP API — żądania WordPressa do usług zewnętrznych.
8. Cloudflare — Error 502 or 504 — 502/504 na warstwie Cloudflare i originu.