Błąd 502 Bad Gateway oznacza, że serwer pośredniczący, np. Nginx, load balancer albo CDN, wysłał żądanie dalej do aplikacji i dostał od niej nieprawidłową odpowiedź albo nie dostał żadnej. Sama aplikacja może przy tym w ogóle nie zapisać błędu, bo problem leży na styku dwóch usług. Dlatego przy błędzie 502 zawsze zaczynam od ustalenia, która warstwa zawiodła. W tym wpisie pokazuję, jak to robię i jak naprawiam najczęstsze przyczyny w konfiguracjach z Nginx, PHP-FPM, Node.js i Cloudflare.
Dlaczego brama zwraca błąd 502
Błąd 500 zgłasza sama aplikacja, a 502 zgłasza serwer, który stoi przed nią i nie dostał od niej poprawnej odpowiedzi. Komunikaty w logu Nginx zwykle od razu wskazują przyczynę:
| Komunikat w logu Nginx | Co oznacza | Co sprawdzam |
|---|---|---|
connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory) | Nginx szuka gniazda PHP-FPM, którego nie ma | czy PHP-FPM działa i czy ścieżka gniazda zgadza się z konfiguracją |
connect() ... failed (111: Connection refused) | aplikacja nie nasłuchuje na danym porcie | czy proces Node.js lub PHP-FPM nie padł albo nie zmienił portu |
(11: Resource temporarily unavailable) | kolejka połączeń do PHP-FPM jest pełna | liczbę procesów PHP-FPM i obciążenie serwera |
upstream prematurely closed connection | aplikacja zerwała połączenie w trakcie odpowiedzi | log aplikacji, brak pamięci, zabite procesy |
upstream sent too big header | nagłówki odpowiedzi są większe niż bufor Nginx | rozmiar ciasteczek i nagłówków, ustawienia buforów |
Jak diagnozuję i naprawiam błąd 502
1. Ustalam, kto zwraca błąd
Jeśli strona stoi za Cloudflare lub innym CDN, najpierw sprawdzam, czy błąd generuje CDN, czy serwer źródłowy. Strona błędu Cloudflare pokazuje, która warstwa nie działa, a kody z zakresu 520–526 oznaczają problemy specyficzne dla połączenia CDN z serwerem. Żeby pominąć CDN, wysyłam żądanie bezpośrednio na adres IP serwera:
curl -I --resolve example.pl:443:203.0.113.10 https://example.pl/Jeśli serwer odpowiada poprawnie, a przez CDN pojawia się 502, przyczyna leży w połączeniu między nimi: zapora blokująca adresy CDN, nieprawidłowy certyfikat na serwerze albo zła konfiguracja trybu SSL. Te ustawienia sprawdzam razem z resztą, którą obejmuje konfiguracja CDN.
2. Sprawdzam, czy aplikacja działa
systemctl status php8.3-fpm
tail -n 50 /var/log/nginx/error.log
pm2 logs --lines 50Pierwsze polecenie pokazuje stan PHP-FPM, drugie ostatnie błędy Nginx, a trzecie logi aplikacji Node.js uruchomionej przez PM2. Jeśli proces nie działa, uruchamiam go ponownie, ale zawsze szukam w logach, dlaczego się zatrzymał. Restart bez znalezienia przyczyny zwykle kończy się powrotem błędu przy następnym większym ruchu.
3. Szukam braku pamięci i limitów procesów
Najczęstsza przyczyna 502 na serwerach VPS to brak pamięci. System zabija wtedy procesy PHP-FPM, bazy danych albo Node.js. Sprawdzam to w logu jądra:
dmesg -T | grep -i "out of memory"
grep "max_children" /var/log/php8.3-fpm.logKomunikat o osiągnięciu pm.max_children oznacza, że wszystkie procesy PHP-FPM były zajęte i kolejne żądania nie miały kto
obsłużyć. Liczbę procesów dobieram do pamięci serwera: dzielę pamięć, którą mogę przeznaczyć na PHP, przez średnie zużycie jednego
procesu. Zwiększanie limitu ponad możliwości serwera zamienia błędy 502 w brak pamięci. Na hostingu współdzielonym tych limitów nie da się
zmienić, więc gdy strona regularnie je przekracza, wracam do pytania,
jaki hosting pasuje do projektu.
4. Poprawiam konfigurację proxy
Gdy log zgłasza za duże nagłówki, co zdarza się przy wielu ciasteczkach albo rozbudowanych nagłówkach bezpieczeństwa, zwiększam bufory:
fastcgi_buffer_size 32k;
fastcgi_buffers 16 16k;
proxy_buffer_size 32k;
proxy_buffers 8 32k;Po każdej zmianie sprawdzam konfigurację poleceniem nginx -t i dopiero wtedy przeładowuję serwer. Zwracam też uwagę, czy
ścieżka gniazda albo port w konfiguracji Nginx zgadzają się z tym, na czym faktycznie nasłuchuje aplikacja. Po aktualizacji PHP nazwa
gniazda zmienia się razem z numerem wersji i to częsta przyczyna nagłego 502 po pracach na serwerze.
Błąd 502 a 504
Oba błędy zgłasza serwer pośredniczący, ale oznaczają co innego. Przy 502 aplikacja odpowiedziała błędnie albo zerwała połączenie, a przy błędzie 504 w ogóle nie zdążyła odpowiedzieć w wyznaczonym czasie. Pierwszy zwykle oznacza, że proces nie działa albo padł, drugi, że działa, ale za wolno. Przyczyny obu szukam w logach serwera i aplikacji, a pomaga mi w tym regularna analiza logów serwera.
Pozostałe błędy HTTP
Każdy kod błędu wskazuje na inną warstwę, więc diagnozę zaczynam od innego miejsca: