504 Gateway Timeout: co oznacza i jak naprawić

Czym jest błąd 504 Gateway Timeout?

504 Gateway Timeout to kod statusu HTTP oznaczający, że serwer działający jako brama lub proxy nie otrzymał na czas odpowiedzi od serwera upstream. Proxy czekało na odpowiedź, ale trwało to zbyt długo, więc się poddało i zwróciło przeglądarce błąd 504.

Definiuje go RFC 9110: „Kod statusu 504 (Gateway Timeout) oznacza, że serwer, działając jako brama lub proxy, nie otrzymał na czas odpowiedzi od serwera upstream, do którego musiał się zwrócić, aby zrealizować żądanie” (RFC 9110 §15.6.5).

Kluczowe jest słowo gateway. W błędzie 504 zawsze biorą udział co najmniej dwa serwery: ten, z którym się połączyłeś (proxy/brama), i ten za nim (upstream/origin), który nie odpowiedział. Typowe proxy to reverse proxy Nginx, Cloudflare, AWS Application Load Balancer (ALB) i CloudFront.

Jak wygląda błąd 504

Treść zależy od tego, która warstwa się poddała:

• 504 Gateway Time-out z napisem „nginx” poniżej: nginx (pisze to z łącznikiem)
• 504 Gateway Time-out · The server didn't respond in time.: domyślna strona HAProxy
• Gateway Timeout · The gateway did not receive a timely response from the upstream server or application.: Apache przed PHP-FPM (mod_proxy_fcgi). Apache jako proxy dla backendu HTTP pokazuje zamiast tego Proxy Error · Error reading from remote server (to 502).
• ERROR · The request could not be satisfied · 504 ERROR: Amazon CloudFront
• Error 524: A timeout occurred: wersja Cloudflare; dotarł do Twojego serwera, ale odpowiedź nie nadeszła na czas
• Ta strona nie działa · Serwer example.com potrzebował zbyt wiele czasu na odpowiedź. · Błąd HTTP 504: Chrome, gdy 504 nie ma własnej strony

Niezależnie od treści przyczyna jest ta sama: proxy czekało na serwer za sobą, a odpowiedź nie nadeszła na czas. (Chrome używa tego samego zdania „potrzebował zbyt wiele czasu na odpowiedź”, gdy przeglądarka w ogóle nie mogła się połączyć, ale wtedy nagłówek brzmi „Ta witryna jest nieosiągalna”, a kod to ERR_CONNECTION_TIMED_OUT, nie Błąd HTTP 504: zobacz ERR_CONNECTION_TIMED_OUT.)

Jak dochodzi do błędu 504 Gateway Timeout

Aby zrozumieć błąd 504, trzeba poznać łańcuch timeoutów między przeglądarką a serwerem origin. Typowe żądanie przechodzi przez wiele warstw, a każda ma własne ustawienie timeoutu.

Typowy przebieg żądania: Przeglądarka → CDN (Cloudflare) → Load balancer → Nginx → PHP-FPM → Baza danych. Jeśli zapytanie do bazy trwa 90 sekund, a fastcgi_read_timeout w nginx wynosi 60 sekund, nginx przestaje czekać i zwraca 504 do load balancera, który przekazuje go przez CDN do Twojej przeglądarki.

Serwer, który zwraca 504, to zwykle proxy pośrodku, a nie sama aplikacja. Aplikacja może nadal przetwarzać żądanie albo być zawieszona.

Źródła: Cloudflare 524, ustawienia origin w CloudFront, Google Cloud i dokumentacja każdego serwera. Własny max_execution_time w PHP (30 sekund) nie daje 504: skrypt, który go osiągnie, zatrzymuje się z błędem krytycznym, widocznym jako 500. Na Linuksie nie liczy też czasu oczekiwania na bazę danych ani inne operacje I/O, więc skrypt zablokowany na wolnym zapytaniu może działać znacznie dłużej.

Najczęstsze przyczyny błędu 504 Gateway Timeout

Typowe powody, dla których proxy przestaje czekać:

• Wolne żądanie — ciężkie zapytanie do bazy, raport lub wywołanie wolnego zewnętrznego API trwa dłużej niż timeout proxy.
• Przeciążony serwer — CPU na 100%, brak pamięci albo wszystkie workery PHP-FPM zajęte, więc nowe żądania czekają w kolejce, aż proxy się podda.
• Wąskie gardła w bazie danych — wolne zapytania, brakujące indeksy, zablokowane tabele lub wyczerpana pula połączeń.
• Zbyt niskie timeouty — 60 sekund w nginx to za mało dla backendu, który naprawdę potrzebuje więcej czasu (eksport, import, duży upload).
• Problemy sieciowe między proxy a origin — utrata pakietów lub zapora, która po cichu odrzuca pakiety proxy (zapora, która je odrzuca jawnie, daje 502).
• Stały limit CDN — Cloudflare czeka 125 sekund w planach Free, Pro i Business, niezależnie od ustawień nginx, a potem pokazuje Error 524.
• Zalew ruchu — skok liczby żądań lub atak zajmuje workery, więc zwykłe żądania nie dostają odpowiedzi na czas. (Serwer, który wie o swoim przeciążeniu, może zamiast tego odpowiedzieć 503.)

Rozwiązanie dla odwiedzających: co możesz zrobić

Jeśli widzisz błąd 504 na cudzej stronie, problem leży po stronie ich serwera, nie Twojego urządzenia. Warto jednak spróbować kilku rzeczy.

• Odczekaj minutę i odśwież — wiele błędów 504 trwa tylko tyle, ile gorący moment na serwerze.
• Sprawdź, czy strona nie działa dla wszystkich — Website Down Checker otwiera stronę z 11 miejsc. Jeśli tam też jest 504, problem leży w witrynie.
• Spróbuj innej sieci — dane mobilne zamiast Wi-Fi albo bez VPN, na wypadek gdyby to Twoje proxy lub VPN było bramą, która przekracza czas.
• Zajrzyj na stronę statusu lub profile społecznościowe witryny — popularne serwisy często informują o awariach.

Rozwiązanie 1: zwiększ ustawienia timeout (Nginx i Apache)

Najczęstszą poprawką błędów 504 jest zwiększenie wartości timeoutów na reverse proxy. Jeśli Twój backend faktycznie potrzebuje więcej niż 60 sekund (wartość domyślna), proxy musi wiedzieć, że ma czekać dłużej.

# nginx — reverse proxy to a backend (Node.js, Python, etc.)
location / {
    proxy_pass http://backend;
    proxy_read_timeout 300;
    proxy_send_timeout 300;
}

# nginx — FastCGI (PHP-FPM)
location ~ \.php$ {
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    fastcgi_read_timeout 300;
    fastcgi_send_timeout 300;
    include fastcgi_params;
}

# Leave proxy_connect_timeout / fastcgi_connect_timeout at their defaults:
# nginx caps them at about 75 seconds, and a dead backend should fail fast.

W Apache dodaj ProxyTimeout 300 w VirtualHost albo użyj ProxyPass / http://backend:8080/ timeout=300 dla jednego backendu.

Ważne: timeouty odczytu i wysyłania mierzą przerwę między dwiema kolejnymi operacjami odczytu lub zapisu, a nie łączny czas transferu. Zatem proxy_read_timeout 300 oznacza „jeśli przez 300 sekund nie nadejdą żadne dane”, a nie „cała odpowiedź musi zakończyć się w 300 sekund”. Po zmianie przeładuj konfigurację: sudo nginx -t && sudo systemctl reload nginx.

Za CDN obowiązuje także jego własny limit: Cloudflare ucina po 125 sekundach (od Free do Business), a CloudFront domyślnie po 30, więc podniesienie wartości w nginx ponad te limity nic nie zmieni dla odwiedzających, którzy przychodzą przez CDN.

Rozwiązanie 2: zoptymalizuj wolne skrypty i zapytania do bazy danych

Jeśli Twój backend stale przekracza timeout, zwiększanie jego wartości tylko maskuje problem. Prawdziwa naprawa to przyspieszenie backendu.

• Znajdź wolne zapytania — Włącz log wolnych zapytań MySQL (slow_query_log = 1, long_query_time = 1) lub użyj EXPLAIN ANALYZE na podejrzanych zapytaniach. Dodaj brakujące indeksy, unikaj SELECT * i stronicuj duże zbiory wyników.
• Dodaj cache — Użyj Redis lub Memcached, aby cache'ować wyniki kosztownych zapytań. Zapytanie, które przy każdym załadowaniu strony trwa 5 sekund, powinno być cache'owane.
• Przenieś ciężką pracę do zadań w tle — Generowanie raportów, wysyłka e-maili, przetwarzanie obrazów i importy danych powinny działać w kolejce zadań (Celery, Sidekiq, Bull), a nie w cyklu żądania HTTP.
• Zoptymalizuj wywołania API — Jeśli backend wywołuje wolne zewnętrzne API, dodaj do tych wywołań timeouty i wdróż circuit breakery, aby jedno wolne API nie blokowało wszystkich żądań.
• Ogranicz zapytania N+1 — Zapytania generowane przez ORM często wykonują setki pojedynczych wywołań bazy. Użyj eager loadingu lub zapytań wsadowych, aby zmniejszyć liczbę rund.

Rozwiązanie 3: sprawdź zasoby serwera (CPU, RAM, dysk)

Jeśli serwer origin jest przeciążony, nie przetwarza żądań dość szybko, a proxy przekracza czas oczekiwania. Sprawdź, co zużywa zasoby.

# Check CPU and memory usage
top -bn1 | head -20

# Check disk space (full disk = silent failures)
df -h

# Check memory details
free -m

# Find processes using the most CPU
ps aux --sort=-%cpu | head -10

# Find processes using the most memory
ps aux --sort=-%mem | head -10

# Check active network connections
ss -s

Jeśli CPU lub RAM jest wykorzystane w ponad 90%, musisz zoptymalizować aplikację, zabić wymykające się spod kontroli procesy albo rozbudować serwer. Jeśli dysk jest pełny, usuń stare logi, kopie zapasowe lub pliki tymczasowe; pełny dysk może po cichu wywrócić bazy danych i wywołać lawinę błędów 504.

Rozwiązanie 4: sprawdź logi błędów

Logi błędów mówią dokładnie, dlaczego proxy zwróciło 504. Zawsze zajrzyj do logów, zanim zaczniesz zgadywać przyczynę.

# Nginx error log (look for "upstream timed out")
tail -50 /var/log/nginx/error.log

# Apache error log
tail -50 /var/log/apache2/error.log       # Debian/Ubuntu
tail -50 /var/log/httpd/error_log          # CentOS/RHEL

# PHP-FPM log
tail -50 /var/log/php8.3-fpm.log

# System log (OOM kills, crashes)
tail -50 /var/log/syslog

Typowe komunikaty w logach przy błędzie 504:

„upstream timed out (110: Connection timed out) while reading response header from upstream” (nginx): backend potrzebował więcej czasu niż proxy_read_timeout (lub fastcgi_read_timeout). Przyspiesz go albo zwiększ timeout, jeśli to czekanie jest uzasadnione.

„upstream timed out (110: Connection timed out) while connecting to upstream” (nginx): nginx nie zdołał nawet połączyć się na czas: zapora odrzuca pakiety albo backend jest zbyt zajęty, by przyjmować połączenia.

„server reached pm.max_children setting” (PHP-FPM): wszystkie workery są zajęte, więc żądania czekają w kolejce. Zwiększ pm.max_children tylko wtedy, gdy starczy RAM-u; w przeciwnym razie znajdź wolne żądania, które blokują workery.

„Too many connections” (MySQL): limit połączeń został wyczerpany. Nowe połączenia kończą się od razu błędem (to 500, jak „Error establishing a database connection” w WordPressie), a zapytania, które je trzymają, to często te wolne, stojące za Twoimi błędami 504.

Rozwiązanie 5: dostosuj ustawienia PHP-FPM

W aplikacjach PHP (WordPress, Laravel, Magento) trzymaj timeouty w łańcuchu, w którym każda warstwa jest nieco dłuższa od tej za nią: fastcgi_read_timeout w nginx ≥ request_terminate_timeout w PHP-FPM ≥ max_execution_time w PHP.

Po zmianie ustawień PHP-FPM zrestartuj go (sudo systemctl restart php8.3-fpm, dopasuj wersję). Jeśli fastcgi_read_timeout w nginx jest krótszy niż limity PHP, nginx podda się pierwszy, a odwiedzający zobaczą 504, gdy PHP jeszcze pracuje.

Rozwiązanie 6: sprawdź konfigurację CDN i proxy

Jeśli Twoja strona stoi za CDN, takim jak Cloudflare czy AWS CloudFront, CDN ma własne ustawienia timeoutów, które mogą przesłonić konfigurację serwera.

Cloudflare: w planach Free, Pro i Business, jeśli Twój origin nie zacznie odpowiadać w ciągu 125 sekund, Cloudflare się poddaje i pokazuje Error 524 (Cloudflare). Rada samego Cloudflare: przyspiesz żądanie, przenieś długie zadania w tło albo udostępnij je z subdomeny tylko z DNS (szara chmurka); plany Enterprise mogą podnieść limit.

CloudFront: zwiększ response timeout origin w ustawieniach origin dystrybucji (AWS). AWS radzi najpierw naprawić wolny origin. Przy żądaniach GET i HEAD CloudFront ponawia próby wobec origin (domyślnie 3 próby połączenia), więc origin może zobaczyć to samo żądanie kilka razy, zanim odwiedzający dostanie 504.

Aby sprawdzić, która warstwa wysłała 504, obejrzyj nagłówki odpowiedzi w HTTP Header Checker: server: awselb/2.0 to load balancer AWS, x-cache: Error from cloudfront to CloudFront, a server: nginx to nginx. Za Cloudflare każda odpowiedź zawiera server: cloudflare, więc tam wskazówką jest sam kod (524 lub 504).

Rozwiązanie 7: rozwiązania specyficzne dla WordPress

Strony WordPress szczególnie często dostają błędy 504 przez ciężkie wtyczki, rozdętą bazę danych i limity współdzielonego hostingu. Oto celowane poprawki.

• Znajdź wolne wtyczki — Wyłącz wszystkie wtyczki, a potem włączaj je po jednej. Jeśli nie masz dostępu do wp-admin, zmień nazwę folderu plugins przez SSH: mv wp-content/plugins wp-content/plugins_disabled. Wolne zapytania do bazy wskaże wtyczka Query Monitor.
• Zainstaluj wtyczkę cache — WP Super Cache, W3 Total Cache lub WP Rocket zmniejszają obciążenie serwera, podając statyczny HTML zamiast uruchamiać PHP przy każdym żądaniu.
• Użyj cache obiektów — Zainstaluj Redis lub Memcached oraz wtyczkę object cache dla WordPressa. Cache'uje to wyniki zapytań do bazy w pamięci i zmniejsza obciążenie MySQL.
• Wyczyść bazę danych — Usuń stare rewizje wpisów, transienty, spam w komentarzach i osierocone metadane. Użyj WP-Optimize lub WP-Sweep. Dodaj define('WP_POST_REVISIONS', 5);, aby ograniczyć przyszłe rewizje.
• Przenieś wp-cron na prawdziwy cron — odwiedziny strony uruchamiają WP-Cron, który wykonuje zaległe zadania w żądaniu loopback zajmującym własnego workera PHP. Dodaj define('DISABLE_WP_CRON', true); do wp-config.php, a potem niech serwer uruchamia wp cron event run --due-now co 5 minut.

504 vs 502 vs 503 vs 408: jaka jest różnica?

Te kody błędów HTTP bywają mylone. Oto, co naprawdę oznacza każdy z nich.

Kluczowa różnica: 502 oznacza, że proxy dostało zepsutą odpowiedź albo połączenie zostało odrzucone lub zamknięte; 504 oznacza, że licznik czasu proxy dobiegł końca, gdy upstream milczał. 503 nie wymaga proxy: może go wysłać każdy przeciążony serwer. 408 to timeout po stronie klienta (klasa 4xx), gdy serwer przestał czekać na klienta.

Jeśli widzisz jednocześnie 502 i 504, backend prawdopodobnie sobie nie radzi: żądania, które przekraczają czas, dają 504, a workery, które padają lub są zabijane, dają 502.

Jeśli widzisz 502, a nie 504, nasz poradnik o 502 Bad Gateway omawia komunikaty z logu błędów nginx, które go wyjaśniają, w tym prawdziwy przypadek z tej strony.

Czy błąd 504 wpływa na SEO?

Dokumentacja Google opisuje, co robią błędy 5xx (dokumentacja Google o skanowaniu):

• Skanowanie zwalnia dla całej witryny, proporcjonalnie do liczby adresów URL zwracających błędy serwera.
• Zaindeksowane strony na początku zostają, ale adresy URL, które stale zwracają błąd serwera, są w końcu usuwane.
• Skanowanie stopniowo wraca do normy, gdy serwer znów odpowiada kodem 2xx.

Jak zapobiegać błędom 504 Gateway Timeout

Lepiej zapobiegać, niż gasić pożary. Te praktyki pomogą serwerowi odpowiadać w granicach timeoutów.

• Ustaw monitoring — monitor dostępności, który co kilka minut ładuje kluczowe strony, wychwyci błędy 504, zanim zgłoszą je użytkownicy.
• Dopasuj łańcuch timeoutów — Upewnij się, że timeout CDN ≥ timeout proxy ≥ timeout aplikacji. Niedopasowane wartości powodują nieprzewidywalne błędy 504.
• Wdróż health checki — Load balancery i proxy powinny sprawdzać serwery upstream health checkami i kierować ruch z dala od instancji, które nie odpowiadają.
• Cache'uj agresywnie — Cache'uj zasoby statyczne, odpowiedzi API i zapytania do bazy. Odpowiedź z cache nigdy nie jest na tyle wolna, by spowodować 504.
• Skaluj automatycznie — Użyj skalowania poziomego (więcej instancji), aby skoki ruchu nie przeciążały jednego serwera.
• Wyprowadź ciężką pracę — Przenieś przetwarzanie plików, generowanie raportów, wysyłkę e-maili i masowe importy do kolejek zadań w tle. Nigdy nie wykonuj kosztownej pracy wewnątrz żądania HTTP.
• Monitoruj wolne zapytania — Włącz logowanie wolnych zapytań w MySQL/PostgreSQL. Ustaw alerty dla zapytań trwających dłużej niż 1 sekunda.
• Dbaj o zdrowe zależności — Monitoruj zewnętrzne API, od których zależy backend. Dodaj timeouty i circuit breakery, aby jedno wolne API nie wywołało lawiny błędów 504 u wszystkich użytkowników.