Błąd 502 Bad Gateway: znajdź przyczynę i napraw

Co oznacza ten błąd

502 to odpowiedź serwera, który działa. Serwer WWW z przodu (nginx, Apache, load balancer albo CDN taki jak Cloudflare) odebrał żądanie, przekazał je aplikacji za sobą (PHP-FPM, procesowi Node.js lub Pythona, serwerowi backendu) i nie dostał z powrotem użytecznej odpowiedzi: połączenie zostało odrzucone, zerwane albo wróciły śmieci. „Gateway” to serwer z przodu; „bad” to to, co wróciło z tyłu.

Błąd 502 mówi więc dwie rzeczy naraz: przód działa, a tył nie działa albo jest zepsuty. To znacznie zawęża poszukiwania.

Częste przyczyny

1. Proces aplikacji nie działa. PHP-FPM się wysypał albo został zatrzymany, proces Node.js umarł, kontener się zakończył. Przód w ogóle nie może się połączyć.
2. Aplikacja jest przeciążona. Wszystkie procesy robocze PHP-FPM są zajęte, kolejka pełna, nowe połączenia odrzucane. Często po skoku ruchu albo przez wolne zapytanie do bazy, które blokuje każdy proces.
3. Zły socket albo port w konfiguracji. Po aktualizacji albo zmianie wersji PHP nginx nadal wskazuje php8.2-fpm.sock, a nowa pula nasłuchuje na php8.4-fpm.sock.
4. Zbyt krótkie limity czasu. Backend odpowiada, ale później, niż przód jest gotów czekać. Jedne konfiguracje zgłaszają to jako 502, inne jako błąd 504 Gateway Timeout.
5. Backend wysyła za duży nagłówek albo niepoprawną odpowiedź. Typowe dla frameworków, które dużo pakują do ciasteczek; nginx loguje wtedy „upstream sent too big header”.
6. CDN nie może dotrzeć do Twojego serwera. Z Cloudflare z przodu strona 502 z logo Cloudflare oznacza, że Cloudflare nie dostał nic z serwera źródłowego: firewall, zły adres IP po przeprowadzce albo serwer po prostu nie działa.

Jeśli odwiedzasz cudzą stronę

Błędu 502 na cudzej stronie nie naprawisz. Odśwież raz po minucie; jeśli się utrzymuje, działać musi właściciel strony. Jeśli to Twoja strona, czytaj dalej.

Jeśli to Twoja strona: najpierw sprawdź

Czy nie działa u wszystkich? Uruchom narzędzie Is it down?. Pokazuje kod statusu z zewnątrz i czy odpowiedział CDN, czy serwer źródłowy.

Hosting współdzielony albo kreator stron? Błąd 502 tam to prawie zawsze problem dostawcy (przeciążona pula PHP na współdzielonym węźle). Przejdź do wiadomości dla dostawcy poniżej.

Własny serwer: zaloguj się przez SSH i zapytaj serwer WWW, co poszło nie tak.

# nginx: ostatnie błędy, najnowsze na dole
sudo tail -n 50 /var/log/nginx/error.log

# Apache (Debian/Ubuntu)
sudo tail -n 50 /var/log/apache2/error.log

Typowe linie i ich znaczenie:

• connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory): PHP-FPM nie działa albo ścieżka socketu jest zła.
• connect() failed (111: Connection refused) while connecting to upstream: port backendu nie nasłuchuje.
• upstream prematurely closed connection: proces backendu wysypał się w trakcie odpowiedzi, często błąd krytyczny PHP albo brak pamięci.
• upstream sent too big header: zwiększ bufory (poniżej).
• (11: Resource temporarily unavailable): wszystkie procesy robocze PHP-FPM są zajęte.

Naprawy na własnym serwerze

1. Uruchom zatrzymaną usługę

# znajdź używaną wersję PHP-FPM
systemctl list-units --type=service | grep -E 'php|fpm'

systemctl status php8.3-fpm
sudo systemctl start php8.3-fpm

# aplikacje Node.js lub Python zarządzane przez systemd
sudo systemctl restart mojaaplikacja

Jeśli usługa nie chce wystartować, powód jest w journalctl -u php8.3-fpm -n 50. Najczęstszy to pełny dysk (df -h), drugi to błąd składni w konfiguracji puli (sudo php-fpm8.3 -t).

2. Popraw socket albo port

Porównaj, z czym łączy się nginx, z tym, na czym nasłuchuje PHP-FPM:

grep -r fastcgi_pass /etc/nginx/sites-enabled/
grep -r '^listen' /etc/php/*/fpm/pool.d/

Oba muszą się zgadzać. Po zmianie zawsze testuj konfigurację przed przeładowaniem:

sudo nginx -t && sudo systemctl reload nginx

Z Apache i PHP-FPM przez mod_proxy_fcgi to samo sprawdzenie dotyczy linii SetHandler "proxy:unix:/run/php/php8.3-fpm.sock|fcgi://localhost"; testuj przez sudo apachectl configtest.

3. Daj PHP-FPM miejsce

Jeśli log błędów mówi, że procesy są zajęte, albo server reached pm.max_children, podnieś limit w pliku puli (/etc/php/8.3/fpm/pool.d/www.conf):

pm = dynamic
pm.max_children = 20
pm.start_servers = 4
pm.min_spare_servers = 2
pm.max_spare_servers = 6

Każdy proces potrzebuje pamięci (często 30 do 80 MB dla WordPressa); sprawdź free -m, zanim podniesiesz liczbę, i poszukaj wolnego zapytania albo wtyczki, która w ogóle zajmuje procesy.

4. Zwiększ bufory dla dużych nagłówków

W bloku server nginx:

fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;
proxy_buffers 8 16k;
proxy_buffer_size 32k;

5. Szczegóły WordPressa

Błąd 502 zaraz po aktualizacji wtyczki albo motywu oznacza zwykle, że PHP kończy się pamięć albo trafia na błąd krytyczny przy każdym żądaniu. Zmień nazwę katalogu wtyczki przez SFTP lub SSH, żeby ją wyłączyć (wp-content/plugins/nazwa-wtyczki na nazwa-wtyczki.off), potem odśwież stronę. Podnieś memory_limit w puli albo php.ini, jeśli journalctl pokazuje „Allowed memory size exhausted”. Z WP-CLI: wp plugin deactivate nazwa-wtyczki.

6. Za Cloudflare

Sprawdź, czy serwer źródłowy odpowiada bezpośrednio: curl -I https://IP-TWOJEGO-SERWERA -H 'Host: przyklad.pl' -k. Jeśli to działa, firewall na serwerze może blokować zakresy adresów Cloudflare albo rekord DNS w Cloudflare wskazuje stary adres IP.

Gdy to problem dostawcy hostingu

Na hostingu współdzielonym nie zrestartujesz PHP-FPM. Wyślij dostawcy to, z czasem i dokładnym błędem:

Dzień dobry, moja strona przyklad.pl zwraca „502 Bad Gateway” od około 14:30 UTC. Sprawdzenie z zewnątrz to potwierdza; po mojej stronie nic się nie zmieniło. Czy mogliby Państwo sprawdzić procesy PHP i serwer WWW na moim koncie hostingowym i dać mi znać, kiedy strona wróci?

Jak zapobiec następnemu

Błąd 502 to prawie zawsze zatrzymany albo przeciążony backend, a oba widać, zanim zauważą odwiedzający: zatrzymana usługa PHP-FPM, kończąca się pamięć, zapełniający się dysk. Monitoring serwerów z agentem przesyła dokładnie to z wnętrza serwera, a sprawdzanie stron z zewnątrz wyłapuje 502 w chwili, gdy się pojawi. Awaria? Naprawiamy: na własnym serwerze Quick Fix może zrestartować zatrzymaną usługę po udanym teście jej konfiguracji; jeśli przyczyna leży głębiej, przejmuje Deep Fix, przez całą dobę. Zobacz naprawa serwera.