Błąd 502 Bad Gateway: co oznacza i jak go naprawić
Błąd 502 Bad Gateway oznacza, że proxy dostało błędną odpowiedź od serwera za nim. Porady dla odwiedzających i administratorów: nginx, PHP-FPM, Cloudflare.
Błąd 502 Bad Gateway oznacza, że serwer działający jako brama lub proxy otrzymał nieprawidłową odpowiedź od serwera, który za nim stoi. Błąd powstaje między dwoma serwerami, więc nie pochodzi z przeglądarki ani z urządzenia odwiedzającego. [1] [2]
Poradnik składa się z dwóch części. Jeśli odwiedzasz stronę, w krótkiej sekcji poniżej znajdziesz, czego możesz spróbować. Jeśli prowadzisz stronę, w części o naprawie ustalisz, który serwer po drodze zwrócił błąd 502, odczytasz wiersz logu, który wskazuje przyczynę, a potem krok po kroku usuniesz błąd i zapobiegniesz jego powrotowi.
Co oznacza błąd 502 Bad Gateway?
Żądanie wysłane do strony internetowej często przechodzi po drodze przez kilka serwerów i usług:
browser → CDN or proxy → web server → application
Każde ogniwo tego łańcucha przekazuje żądanie następnemu. Jeśli serwer stojący za proxy zwróci odpowiedź, której proxy nie może wykorzystać, proxy odpowie kodem 502. Sam kod statusu nie mówi, które ogniwo zawiodło. W nginx błąd 502 pojawia się też wtedy, gdy serwer upstream (backend za proxy) odrzuci połączenie, zresetuje je lub przedwcześnie zamknie, więc kod mówi tylko tyle, że zawiodło połączenie za proxy.
Są też dwie rzeczy, których błąd 502 nie oznacza. Nie świadczy o tym, że odwiedzający wysłał błędne żądanie. Nie oznacza też przekroczenia limitu czasu: gdy serwer upstream odpowiada zbyt wolno, pojawia się inny kod, który omawiamy w następnej sekcji.
502, 503 i 504: czym się różnią
Większość awarii po stronie serwera między ogniwami łańcucha sprowadza się do trzech kodów. Wskazują one różne przyczyny, więc zanim zaczniesz szukać, sprawdź, który kod widzisz.
| Kod | Co się stało | Typowa przyczyna | Co sprawdzić najpierw |
|---|---|---|---|
| 502 Bad Gateway | Brama otrzymała nieprawidłową odpowiedź od serwera upstream [1] [2] | Aplikacja nie działa lub odrzuciła połączenie, uległa awarii w trakcie obsługi żądania albo wysłała nagłówki, których nginx nie może przyjąć | Wiersz logu błędów nginx dotyczący tego żądania |
| 503 Service Unavailable | Serwer chwilowo nie może obsłużyć żądania [1] | Przeciążenie lub planowane prace serwisowe | Obciążenie serwera i to, czy trwają prace |
| 504 Gateway Timeout | Brama nie otrzymała na czas odpowiedzi od serwera upstream [1] [3] | Serwer upstream działa zbyt wolno, na przykład z powodu długiego zapytania do bazy danych, i upłynął limit czasu proxy [4] | Które żądanie jest wolne i co w tym czasie robi aplikacja |
Błąd 504 to problem z czasem: serwer upstream odpowiedział za późno, a nie nieprawidłowo. W nginx domyślne limity czasu odczytu dla proxy i FastCGI wynoszą 60 sekund [4] [5].
Wydłużenie limitu czasu nie naprawi błędu 502
Limity czasu, takie jak proxy_read_timeout i fastcgi_read_timeout, określają tylko, jak długo nginx czeka na odpowiedź. Błąd 502 oznacza, że odpowiedź była uszkodzona, jej zabrakło albo w ogóle nie dotarła. Wydłużenie limitu czasu tego nie zmieni. Limity czasu zmieniaj tylko przy błędzie 504.
Jeśli widzisz błąd 502 jako odwiedzający
Serwera nie naprawisz, ale możesz wykluczyć problem po swojej stronie i zgłosić błąd.
- Odczekaj minutę i odśwież stronę. Jeśli na serwerze trwał restart lub wdrożenie, błąd może sam zniknąć.
- Spróbuj w innej przeglądarce albo w innej sieci, na przykład komórkowej. Jeśli tam strona się wczyta, problem dotyczy tylko twojego połączenia.
- Sprawdź stronę statusu serwisu, jeśli ją udostępnia.
- Zanotuj godzinę i dokładny adres otwieranej strony. Właściciel strony potrzebuje ich, żeby znaleźć odpowiedni wiersz w logu.
Błąd naprawia się zwykle na serwerze, więc usunąć go może tylko właściciel strony. Jeśli to twoja strona, wykonaj poniższe kroki.
Jak naprawić błąd 502 Bad Gateway na swoim serwerze
Zacznij od zewnątrz i posuwaj się w głąb. Każdy krok wyklucza jedno ogniwo, zanim przejdziesz do następnego.
1. Ustal, który serwer zwrócił błąd 502
Pobierz stronę dwa razy. Pierwsze żądanie przechodzi zwykłą, publiczną drogą. Drugie łączy się bezpośrednio z adresem IP twojego serwera źródłowego (origin) i wysyła nazwę domeny w nagłówku Host. Przykładowy adres zastąp własnym.
curl -I "https://www.example.com/"
curl -I --resolve www.example.com:443:203.0.113.10 "https://www.example.com/"W obu odpowiedziach odczytaj wiersz statusu i nagłówki:
- Nagłówki
cf-rayiserver: cloudflareoznaczają, że odpowiedź przeszła przez Cloudflare. Pojawiają się nawet wtedy, gdy błąd 502 pochodzi z twojego serwera źródłowego, więc nie mówią, gdzie powstał błąd; wskazuje to dopiero treść samej strony błędu (zobacz sekcję o Cloudflare poniżej). - Nagłówek
server: nginxw odpowiedzi na bezpośrednie żądanie oznacza, że błąd 502 wygenerował nginx na twoim serwerze źródłowym.
Jeśli bezpośrednie żądanie również zwraca 502, problem leży na serwerze źródłowym – przejdź do kroku 2. Jeśli bezpośrednie żądanie zwraca 200, a publiczne 502, awaria występuje na drodze przed serwerem źródłowym. Sprawdź, co mówi sama strona błędu (sekcja o Cloudflare poniżej), i zajrzyj do kroku 7.
2. Przeczytaj log błędów
Gdy nginx nie może uzyskać od serwera upstream odpowiedzi, którą da się wykorzystać, zapisuje przyczynę w swoim logu błędów. Przeczytaj ostatnie wiersze:
sudo tail -n 50 /var/log/nginx/error.logDopasuj komunikat do przyczyny:
| Wiersz logu (zawiera) | Typowa przyczyna | Co zrobić |
|---|---|---|
connect() failed (111: Connection refused) while connecting to upstream |
Aplikacja nie działa albo nasłuchuje na innym porcie | Uruchom aplikację lub popraw port (krok 3) |
connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory) |
Błędna ścieżka gniazda albo PHP-FPM jest zatrzymany | Sprawdź ścieżkę gniazda i usługę (kroki 3 i 4) |
connect() to unix:/run/php/php8.3-fpm.sock failed (13: Permission denied) |
Właściciel lub uprawnienia gniazda nie pozwalają nginx na połączenie | Sprawdź ustawienia listen.owner, listen.group i listen.mode w puli PHP-FPM |
upstream prematurely closed connection while reading response header from upstream |
Aplikacja uległa awarii lub została zabita w trakcie obsługi żądania, często dlatego, że zabrakło pamięci | Sprawdź pamięć i logi awarii (krok 5) |
upstream sent too big header while reading response header from upstream |
Nagłówki odpowiedzi są większe niż bufor nginx | Zwiększ rozmiar bufora (krok 6) |
no live upstreams while connecting to upstream |
Wszystkie serwery w bloku upstream są oznaczone jako niedziałające | Sprawdź serwery w bloku, a potem aplikację za każdym z nich (krok 3) |
Wiersz logu podaje adres lub gniazdo serwera upstream. Porównaj je z tym, na czym aplikacja faktycznie nasłuchuje.
3. Sprawdź, czy aplikacja działa
Sprawdź usługę oraz port lub gniazdo, na którym nasłuchuje. Wybierz kartę, która pasuje do twojego środowiska.
sudo systemctl status php8.3-fpm
sudo ss -lxp | grep phppm2 status
sudo ss -ltnp | grep 3000sudo systemctl status gunicorn
sudo ss -ltnp | grep 8000Jeśli Node działa u ciebie jako usługa systemd, zamiast pm2 status użyj systemctl status <service>. Jeśli usługa jest zatrzymana, przed ponownym uruchomieniem przeczytaj jej logi, żeby nie stracić informacji o przyczynie awarii. Na przykład: sudo journalctl -u php8.3-fpm -n 100.
4. Sprawdź, czy proxy_pass lub fastcgi_pass pasuje do aplikacji
Adres w konfiguracji nginx musi odpowiadać portowi lub gniazdu z kroku 3. Przy niezgodności w logu pojawiają się wiersze „Connection refused” lub „No such file or directory” z kroku 2.
Odwrotne proxy (reverse proxy) do aplikacji na lokalnym porcie:
location / {
proxy_pass http://127.0.0.1:3000;
}PHP-FPM przez gniazdo uniksowe:
location ~ \.php$ {
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
}Sprawdź konfigurację, a potem przeładuj nginx. Jeśli test się nie powiedzie, przeładowanie nie zostanie wykonane, więc nginx zachowa dotychczasową, działającą konfigurację.
sudo nginx -t && sudo systemctl reload nginx5. Sprawdź pamięć i awarie procesów
Wiersz upstream prematurely closed connection wskazuje na proces, który przestał działać w trakcie obsługi żądania. Na małym VPS zwykle odpowiada za to OOM killer, czyli mechanizm jądra, który zabija procesy, gdy brakuje pamięci. Przeszukaj log jądra:
sudo dmesg -T | grep -i -E "out of memory|killed process"
free -hW przypadku PHP-FPM poszukaj w jego logu błędów komunikatu server reached pm.max_children setting. Oznacza on, że wszystkie procesy potomne są zajęte. Każdy proces zużywa pamięć RAM, więc zwiększaj pm.max_children dopiero wtedy, gdy upewnisz się, że serwer ma wolną pamięć na dodatkowe procesy [6].
Jeśli pamięci jest po prostu za mało dla tej strony, rozwiązaniem jest większy plan, a nie dłuższy limit czasu. Jak niedobór pamięci objawia się spowolnieniami, opisujemy w artykule o typowych wąskich gardłach wydajności VPS.
6. Napraw błędy 502 spowodowane rozmiarem nagłówków
Jeśli w logu widać upstream sent too big header, nagłówki odpowiedzi serwera upstream są większe niż bufor nginx. Zwiększ bufor w danym bloku location. Poniższe wartości są przykładowe – dobierz je do swojego największego nagłówka.
location / {
proxy_pass http://127.0.0.1:3000;
proxy_buffer_size 16k;
proxy_buffers 8 16k;
}W przypadku PHP-FPM użyj w ten sam sposób dyrektyw fastcgi_buffer_size i fastcgi_buffers w bloku location z fastcgi_pass [5]. Domyślne wartości dyrektyw i ich dokładną składnię sprawdź w dokumentacji modułu [4]. Możesz też zmniejszyć nagłówki wysyłane przez aplikację, na przykład zbyt duże pliki cookie. Potem sprawdź konfigurację i przeładuj nginx tak jak w kroku 4.
7. Sprawdź zaporę między proxy a serwerem źródłowym
Jeśli proxy działa na innym hoście albo z twoim serwerem źródłowym łączy się usługa taka jak Cloudflare, reguła zapory może blokować to połączenie. Proxy nie dostaje wtedy odpowiedzi, którą mogłoby wykorzystać, i zwraca 502. Sprawdź, czy serwer źródłowy przyjmuje połączenia z adresów proxy na porcie, z którego korzysta proxy. W Ubuntu z ufw:
sudo ufw status verboseJeśli używasz innej zapory, sprawdź jej reguły.
Błąd 502 za Cloudflare
Treść strony błędu wskazuje, gdzie powstał błąd. Według Cloudflare strona błędu 502 lub 504 z oznaczeniami Cloudflare pochodzi z twojego serwera źródłowego. Prosta strona bez oznaczeń Cloudflare może pochodzić od samego Cloudflare, ale Cloudflare wymienia też problem z kompresją na serwerze źródłowym jako przyczynę błędów 502 wyświetlanych bez oznaczeń [7]. Oznaczenia rozstrzygają więc większość przypadków, ale nie wszystkie. Jeśli strona błędu nie ma oznaczeń Cloudflare, a serwer źródłowy odpowiada bezpośrednio kodem 200, sprawdź ustawienia kompresji na serwerze źródłowym.
Czy błąd 502 szkodzi SEO?
Krótkotrwały błąd 502 niewiele szkodzi. Według dokumentacji Google o robotach indeksujących odpowiedzi 5xx i 429 sprawiają, że roboty zwalniają skanowanie. Adresy URL, które stale zwracają błędy serwera, w końcu wypadają z indeksu, choć zaindeksowane adresy są początkowo zachowywane. Gdy serwer znów zwraca odpowiedzi 2xx, skanowanie ponownie przyspiesza [8].
Wniosek praktyczny: szybko usuń przyczynę. Błąd, który powtarza się przez dłuższy czas, może obniżyć pozycję strony w wynikach wyszukiwania.
Jak zapobiegać błędom 502
- Monitoruj stronę z zewnątrz. Dzięki zewnętrznemu monitoringowi dowiesz się o błędzie 502, gdy tylko się pojawi, a nie dopiero wtedy, gdy zgłosi go odwiedzający. Zobacz narzędzia do monitorowania dostępności.
- Zadbaj o wystarczającą ilość RAM. Wiersze „prematurely closed connection” w logu biorą się właśnie z zabijania procesów przy braku pamięci. Jeśli na serwerze regularnie brakuje pamięci, przeczytaj o oznakach, że VPS potrzebuje więcej zasobów oraz o typowych problemach z hostingiem VPS i ich rozwiązaniach.
- Automatycznie restartuj aplikację po awarii. Jednostka systemd z zasadą ponownego uruchamiania przywraca aplikację do działania, gdy ta ulegnie awarii.
Restart=on-failureuruchamia proces ponownie tylko wtedy, gdy zakończy on działanie z błędem. Nie usuwa to jednak błędu w aplikacji, który spowodował awarię, więc zachowaj wiersze logu z kroku 2.
[Service]
ExecStart=/usr/bin/node /srv/myapp/server.js
Restart=on-failure
RestartSec=5- Dodaj test stanu (health check). Udostępnij w aplikacji endpoint, który zwraca 200 tylko wtedy, gdy aplikacja może obsługiwać żądania, i monitoruj ten endpoint. Proces, który działa, ale się zawiesił, zostanie wtedy wykryty jako awaria.
- Sprawdź zawczasu, gdzie szukać, gdy serwer się zatrzyma. Jeśli serwer sam z siebie przestaje odpowiadać, przeczytaj, dlaczego serwer zatrzymuje się bez wyraźnej przyczyny.
Przygotuj się na kolejną awarię
Zanim dojdzie do incydentu, zapisz port lub gniazdo, na którym nasłuchuje aplikacja, ścieżkę do logów i polecenie restartu. Naprawa w kroku 2 zależy od dokładnego wiersza logu, a najszybsze przywrócenie działania – od znajomości nazwy usługi.
Samodzielna naprawa na VPS w StealthRDP
Plany VPS z Linuksem w StealthRDP obejmują pełny dostęp root, więc serwerem WWW i aplikacją zarządzasz samodzielnie, a każdy krok z tego poradnika wykonasz na własnym serwerze. Aby porównać plany, zajrzyj na stronę VPS z Linuksem i do zestawienia planów VPS.
Źródła i odnośniki
- RFC 9110: HTTP Semantics — RFC Editor (IETF) (dostęp: 2026-10-10)
- 502 Bad Gateway — MDN Web Docs (Mozilla) (dostęp: 2026-10-10)
- 504 Gateway Timeout — MDN Web Docs (Mozilla) (dostęp: 2026-10-10)
- Module ngx_http_proxy_module — nginx (dostęp: 2026-10-10)
- Module ngx_http_fastcgi_module — nginx (dostęp: 2026-10-10)
- PHP: Configuration (FPM) — The PHP Group (dostęp: 2026-10-10)
- Error 502 or 504 — Cloudflare (dostęp: 2026-10-10)
- How HTTP Status Codes Affect Google's Crawlers — Google (dostęp: 2026-10-10)
Czytaj dalej
Ochrona VPS przed DDoS: co sprawdzić i jak ją skonfigurować
Jak ocenić ochronę VPS przed DDoS u dostawcy i zbudować własną, wielowarstwową obronę: od zapory i filtrowania ruchu po monitoring i przywracanie działania.
VPS Windows czy Linux: który system wybrać dla firmy?
VPS Windows czy Linux? Porównujemy licencje, zużycie zasobów, oprogramowanie, zarządzanie i bezpieczeństwo. Sprawdź, który system pasuje do twoich zadań.
8 sygnałów, że najwyższy czas na zwiększenie zasobów VPS
Poznaj sygnały, że twój VPS wymaga zwiększenia zasobów – od wolnego ładowania strony po ostrzeżenia o limitach – i zadbaj o optymalną wydajność witryny.
