NetSendo
Guides & Tips

Nginx 502 „upstream sent too big header”: jak to naprawić

NetSendo Team13 min czytania
Nginx 502 „upstream sent too big header”: jak to naprawić

Nginx zapisuje w logu „upstream sent too big header while reading response header from upstream” i zwraca 502 Bad Gateway, gdy nagłówki odpowiedzi Twojej aplikacji (PHP-FPM, kontenera, innego proxy) nie mieszczą się w jednym buforze, który nginx na nie rezerwuje. Domyślnie ten bufor ma rozmiar jednej strony pamięci, na większości serwerów z Linuksem 4 KB. Rozwiązanie: zwiększ fastcgi_buffer_size (dla PHP-FPM) albo proxy_buffer_size (dla reverse proxy) na tej warstwie nginx, która zgłosiła błąd, a potem sprawdź, dlaczego nagłówki tak urosły.

W skrócie: Błąd dotyczy nagłówków odpowiedzi, nie treści strony i nie żądania. Zmierz je poleceniem curl -s -o /dev/null -w '%{size_header}\n'; wszystko w okolicach 4 KB nie przejdzie przy ustawieniach domyślnych. Tam, gdzie nginx rozmawia z PHP-FPM, ustaw fastcgi_buffer_size 32k; fastcgi_buffers 16 16k;, a tam, gdzie przekazuje ruch do innego serwera, proxy_buffer_size 32k; proxy_buffers 8 16k; proxy_busy_buffers_size 64k;, uruchom nginx -t i przeładuj. Przy dwóch warstwach nginx (proxy na hoście przed kontenerem) poprawiasz tę, w której logu jest błąd, a po naprawie wewnętrznej zwykle wysypuje się zewnętrzna. Potem odchudź nagłówki u źródła: najczęstsze przyczyny to sesje trzymane w ciasteczku i nagłówek Link z preloadem w Laravelu.

Co oznacza „upstream sent too big header”?

Serwer docelowy (upstream) wysłał linię statusu i nagłówki większe niż bufor, w który nginx wczytuje początek odpowiedzi, więc nginx uznaje odpowiedź za nieprawidłową i zwraca klientowi 502. „Upstream” to wszystko, do czego nginx przekazuje żądanie: PHP-FPM przez FastCGI, serwer aplikacji po HTTP albo kolejny nginx.

Dokumentacja modułu FastCGI mówi to wprost: bufor na pierwszą część odpowiedzi zwykle zawiera niewielki nagłówek, a jeśli nagłówek go przekroczy, odpowiedź jest uznawana za nieprawidłową. Domyślnie bufor ma rozmiar jednej strony pamięci, czyli 4K albo 8K zależnie od platformy. Moduł proxy ma tę samą regułę dla proxy_buffer_size. Na Linuksie x86-64 strona ma 4096 bajtów; sprawdzisz to poleceniem getconf PAGESIZE.

Bufor nagłówków odpowiedzi

Pojedynczy bufor na połączenie (fastcgi_buffer_size, proxy_buffer_size oraz odpowiedniki uwsgi_, scgi_ i grpc_), w którym musi się zmieścić naraz cała linia statusu i wszystkie nagłówki odpowiedzi. Treść może trafić do kolejnych buforów albo pliku tymczasowego; nagłówki nie.

Trzy rzeczy, którymi ten błąd nie jest. Nie dotyczy żądania: za duże nagłówki lub ciasteczka wysłane przez przeglądarkę dają 400 „Request Header Or Cookie Too Large”, a za to odpowiada large_client_header_buffers. Nie dotyczy treści: strona HTML o wadze 5 MB przechodzi przez ten sam 4-kilobajtowy bufor nagłówków bez problemu. I nie pomoże wyłączenie buforowania: przy proxy_buffering off nginx nadal wczytuje nagłówki do bufora o rozmiarze proxy_buffer_size.

Jak potwierdzić, że to właśnie ten błąd?

Znajdź dokładną linię w logu błędów nginx na serwerze, który zwrócił 502, a potem zmierz nagłówki odpowiedzi problematycznego adresu curlem. Błąd 502 ma kilka możliwych przyczyn i to linia w logu je rozróżnia.

# nginx zainstalowany na hoście
sudo grep "too big header" /var/log/nginx/error.log | tail -n 3

# nginx w Dockerze (oficjalny obraz wysyła log błędów na stderr)
docker compose logs webserver 2>&1 | grep "too big header" | tail -n 3

Taką linię dostaliśmy ze standardowego kontenera nginx:alpine (nginx 1.31.8) przed php:8.3-fpm-alpine, gdy skrypt PHP wysłał 4 KB nagłówków Set-Cookie:

[error] 21#21: *25 upstream sent too big header while reading response header from upstream, client: 172.18.0.4, server: , request: "GET /index.php?kb=8 HTTP/1.1", upstream: "fastcgi://172.18.0.2:9000", host: "127.0.0.1"

Zwróć uwagę na pole upstream:. fastcgi:// oznacza, że ten nginx rozmawia z PHP-FPM i potrzebuje dyrektyw fastcgi_; http:// oznacza, że przekazuje ruch do innego serwera HTTP i potrzebuje dyrektyw proxy_.

Zmierz nagłówki

Przeglądarka nie pokaże nagłówków odpowiedzi 502, bo nginx je odrzucił. Zapytaj backend bezpośrednio, z pominięciem warstwy, która zawodzi, i policz bajty:

# łączna liczba bajtów nagłówków jednej odpowiedzi (w formacie HTTP/1)
curl -s -o /dev/null -w '%{size_header}\n' http://127.0.0.1:8080/login

# same nagłówki, od największego
curl -s -o /dev/null -D - http://127.0.0.1:8080/login | awk '{ print length($0), $1 }' | sort -rn | head

Używaj GET, a nie curl -I: niektóre aplikacje odpowiadają na HEAD innymi nagłówkami. Powtórz pomiar z ciasteczkami zalogowanej sesji (-b 'laravel_session=…'), bo największe nagłówki często pojawiają się dopiero po zalogowaniu albo na jednej konkretnej stronie. Jeśli suma zbliża się do 4096 bajtów lub je przekracza, masz przyczynę.

Linia w logu błędówKodCo zwykle oznacza
upstream sent too big header while reading response header from upstream502Nagłówki odpowiedzi większe niż *_buffer_size
connect() failed (111: Connection refused) while connecting to upstream502Pod adresem upstreamu nikt nie nasłuchuje (backend nie działa albo nieaktualny adres IP kontenera)
upstream prematurely closed connection while reading response header from upstream502Proces backendu padł albo zamknął połączenie w trakcie żądania
upstream timed out (110: Connection timed out) while reading response header from upstream504Backend jest za wolny; problem z limitem czasu, nie z buforem

Stan na listopad 2026, nginx 1.31.8. Dwie pierwsze linie odtworzyliśmy w naszym środowisku testowym; pozostałe to standardowe komunikaty nginx.

Skąd biorą się tak duże nagłówki?

Prawie zawsze z jednego z czterech źródeł: ciasteczek, nagłówków Link z preloadem, tokenów albo nagłówków debugowania. Typowa odpowiedź bez nich ma znacznie poniżej 1 KB, więc do 4 KB musi coś urosnąć.

  • Sesje w ciasteczku. Przy sterowniku sesji cookie w Laravelu sesje są przechowywane w bezpiecznych, zaszyfrowanych ciasteczkach (dokumentacja Laravela). Wszystko, co trafia do sesji, łącznie z danymi flash i starymi wartościami formularza, wraca zaszyfrowane w Set-Cookie przy każdej odpowiedzi. Szyfrowanie i base64 sprawiają, że ciasteczko jest większe niż same dane. Przeglądarki muszą przyjąć „co najmniej 4096 bajtów na ciasteczko” (RFC 6265, sekcja 6.1), więc sama sesja w ciasteczku może się zbliżyć do domyślnego bufora nginx.
  • Wiele nagłówków Set-Cookie. Sesja, token CSRF, „zapamiętaj mnie”, zgody na cookies, testy A/B i analityka: każde ciasteczko to osobny nagłówek z własnymi atrybutami Path, Expires, SameSite i Secure.
  • Nagłówki Link z preloadem. Middleware AddLinkHeadersForPreloadedAssets w Laravelu wpisuje do jednego nagłówka Link każdy skrypt i arkusz stylów, który helper Vite oznaczył do preloadu (kod frameworka). Oficjalne starter kity Laravela dodają ten middleware do grupy web (starter kit Vue). Strona podzielona na ponad 25 chunków z bezwzględnymi adresami daje nagłówek o rozmiarze kilku kilobajtów.
  • Tokeny i dane debugowania. JWT w ciasteczkach lub własnych nagłówkach, nagłówki Content-Security-Policy z długimi listami domen i paski deweloperskie wysyłające dane w nagłówkach.

Ponieważ ciasteczka zależą od sesji, a nagłówki preload od strony, błąd zwykle dotyka tylko niektórych adresów i tylko części użytkowników. „Działa, gdy przechodzę po aplikacji, a po odświeżeniu strony jest 502” to typowy objaw nagłówka Link: nawigacja wewnątrz aplikacji SPA pobiera JSON, a pełne wczytanie strony zwraca HTML z listą wszystkich chunków.

fastcgi_buffer_size czy proxy_buffer_size: co zmienić?

Zmień moduł zgodny z polem upstream: w logu: fastcgi_buffer_size tam, gdzie nginx przekazuje żądania do PHP-FPM przez fastcgi_pass, i proxy_buffer_size tam, gdzie robi to przez proxy_pass. Zmiana tej drugiej nic nie da.

DyrektywaUżywana zDomyślnie (bajty)Nasza wartość
fastcgi_buffer_sizefastcgi_pass (PHP-FPM)4k lub 8k (jedna strona)32k
fastcgi_buffersfastcgi_pass8 × 4k lub 8k16 16k
fastcgi_busy_buffers_sizefastcgi_pass8k lub 16kdomyślna, chyba że nginx -t protestuje
proxy_buffer_sizeproxy_pass (upstream HTTP)4k lub 8k (jedna strona)32k
proxy_buffersproxy_pass8 × 4k lub 8k8 16k
proxy_busy_buffers_sizeproxy_pass8k lub 16k64k

Wartości domyślne z dokumentacji modułów nginx FastCGI i proxy, stan na listopad 2026.

Dla PHP-FPM:

location ~ \.php$ {
    fastcgi_pass php:9000;
    include fastcgi_params;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;

    # Nagłówki odpowiedzi do 32 KB zamiast jednej strony 4 KB
    fastcgi_buffer_size 32k;
    fastcgi_buffers 16 16k;
}

Dla reverse proxy:

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_set_header Host $host;

    proxy_buffer_size 32k;
    proxy_buffers 8 16k;
    proxy_busy_buffers_size 64k;
}

Dlaczego samo zwiększenie bufora nie przechodzi nginx -t

Jeśli dodasz tylko proxy_buffer_size 16k (albo fastcgi_buffer_size 32k) i zostawisz domyślne *_buffers 8 4k, test konfiguracji odmówi startu. Dostaliśmy dokładnie to:

nginx: [emerg] "proxy_busy_buffers_size" must be less than the size of all "proxy_buffers" minus one buffer in /etc/nginx/nginx.conf:32
nginx: configuration file /etc/nginx/nginx.conf test failed

Powód jest w opisie proxy_busy_buffers_size: domyślnie jego rozmiar to dwa bufory ustawione przez proxy_buffer_size i proxy_buffers. Gdy podniesiesz bufor nagłówków do 16k, domyślny rozmiar „busy” rośnie do 32k, a to więcej niż 8 × 4k = 32k buforów treści minus jeden bufor. Podnieś razem z nim proxy_buffers (8 16k przechodzi), a jeśli ustawiasz proxy_busy_buffers_size jawnie, trzymaj go poniżej sumy proxy_buffers minus jeden bufor: przy 4 × 16k wartość 32k przeszła, a 64k skończyło się tym samym komunikatem. Moduł FastCGI zgłasza ten sam błąd z nazwami fastcgi_. Zauważ, że komunikat wskazuje nginx.conf, a nie plik, który edytowałeś.

Ile to bezpiecznie?

Tyle, żeby zmieściły się zmierzone nagłówki z zapasem, i nie więcej. Bufory są przydzielane na połączenie: bufor nagłówków przy każdym przekazanym żądaniu, pozostałe w miarę potrzeb treści odpowiedzi. 32k z zapasem wystarcza każdej rozsądnej aplikacji. Jeśli potrzebujesz 64k lub więcej, coś generuje nagłówki, z którymi będą mieć kłopot także przeglądarki i CDN-y, i naprawa należy do aplikacji.

Dwie warstwy nginx: którą poprawić?

Tę, w której logu błędów jest ta linia. W typowej instalacji z Dockerem nginx na hoście obsługuje HTTPS i przekazuje ruch do kontenera z nginx, który z kolei przekazuje żądania PHP do PHP-FPM. Każda warstwa ma własne domyślne 4 KB i każda zwraca 502.

Zbudowaliśmy taki łańcuch ze standardowych obrazów (proxy jak na hoście → nginx:alpine → php:8.3-fpm-alpine) i kazaliśmy skryptowi PHP wysyłać coraz więcej nagłówków Set-Cookie po 1 KB:

Dodatkowe nagłówki (KB)Wewnętrzny nginx, FastCGI domyślnieWewnętrzny nginx, fastcgi_buffer_size 32kZewnętrzne proxy domyślnie (wewnętrzny na 32k)Zewnętrzne proxy, proxy_buffer_size 32k
3✓ 200✓ 200✓ 200✓ 200
4✗ 502✓ 200✗ 502✓ 200
10✗ 502✓ 200✗ 502✓ 200
31✗ 502✓ 200✗ 502✓ 200
33✗ 502✗ 502✗ 502✗ 502

Pomiar z 16 listopada 2026, nginx 1.31.8, PHP 8.3 FPM, strona pamięci 4096 bajtów. Odpowiedź z 6 KB dodatkowych ciasteczek miała według curla 6346 bajtów nagłówków.

Z tego wynikają dwie praktyczne lekcje. Po pierwsze, naprawa wewnętrznej warstwy przesuwa awarię na zewnątrz: po zwiększeniu bufora FastCGI te same żądania padały na zewnętrznym proxy, z upstream: "http://…" w jego logu, więc przeglądarka widziała to samo 502. Po drugie, zewnętrzna warstwa przekazuje dalej to, co zwróci wewnętrzna, więc gdy obie są za małe, błąd widać tylko w logu wewnętrznej, dopóki jej nie naprawisz. Przy każdym teście sprawdzaj oba logi.

ℹ️ Uwaga: Load balancery i CDN-y przed nginx mają własne limity nagłówków, których nie zawsze możesz zmienić. To kolejny powód, żeby naprawiać nagłówki u źródła, zamiast podnosić bufory na każdym kolejnym etapie.

Jak zmniejszyć nagłówki u źródła?

Trzymaj sesje na serwerze, wysyłaj mniej linków preload i przestań wkładać dane do ciasteczek. Większe bufory usuwają 502; mniejsze nagłówki sprawiają, że każde żądanie jest tańsze, a Ty trzymasz się z dala od limitów dalej w łańcuchu.

Wyprowadź sesje z ciasteczka

W Laravelu zmień sterownik sesji z cookie na redis albo database. Przeglądarka przechowuje wtedy tylko identyfikator sesji.

# .env
SESSION_DRIVER=redis   # albo: database (wymaga tabeli sessions)

php artisan config:clear

Zmiana sterownika jednorazowo wyloguje wszystkich, bo dotychczasowe sesje zostają w starym magazynie. Przy sterowniku database upewnij się, że tabela sessions istnieje (php artisan make:session-table i php artisan migrate w wersjach Laravela, które jej nie mają w szkielecie).

Ogranicz nagłówek Link

Od Laravela 12 middleware przyjmuje limit: AddLinkHeadersForPreloadedAssets::using(8) wypisuje tylko pierwsze 8 zasobów (kod). Nic więcej się nie zmienia: dyrektywa @vite nadal wstawia do HTML tag <link rel="modulepreload"> dla każdego chunka.

// bootstrap/app.php
use Illuminate\Http\Middleware\AddLinkHeadersForPreloadedAssets;

->withMiddleware(function (Middleware $middleware) {
    $middleware->web(append: [
        AddLinkHeadersForPreloadedAssets::using(8),
    ]);
})

W Laravelu 10 i 11 middleware nie ma metody using(). Tam możesz usunąć go z grupy web (tagi preload w HTML zostają) albo zaktualizować framework.

Przejrzyj ciasteczka

  • Usuń ciasteczka, których nikt już nie czyta, i nie ustawiaj tego samego ciasteczka przy każdej odpowiedzi, jeśli jego wartość się nie zmieniła.
  • W miarę możliwości trzymaj tokeny poza ciasteczkami albo ogranicz ich zawartość; JWT z danymi profilu użytkownika to gotowy problem z nagłówkami.
  • Ciasteczka skryptów zewnętrznych, których serwer nie potrzebuje, ustawiaj po stronie przeglądarki albo na osobnej subdomenie.

✅ Zalety naprawy u źródła

  • Naprawia wszystkie warstwy naraz, także CDN, nad którym nie masz kontroli
  • Mniejsze żądania i odpowiedzi przy każdym wyświetleniu strony
  • Brak dodatkowej pamięci na połączenie po stronie proxy

❌ Na co uważać

  • Zmiana sterownika sesji jednorazowo wylogowuje użytkowników
  • Wymaga wdrożenia, a zmiana bufora tylko przeładowania
  • Ciasteczka firm zewnętrznych mogą być poza Twoją kontrolą

Jak wprowadzić zmianę i ją sprawdzić?

Zmień konfigurację, uruchom nginx -t, przeładuj i powtórz żądanie, które zawodziło, obserwując log. Przeładowanie (reload) wprowadza nowe ustawienia bez zrywania otwartych połączeń.

  1. Sprawdź konfigurację

    sudo nginx -t na hoście albo docker compose exec webserver nginx -t w kontenerze. Każdy [emerg] popraw, zanim pójdziesz dalej.

  2. Przeładuj

    sudo systemctl reload nginx (albo sudo nginx -s reload); w Dockerze docker compose exec webserver nginx -s reload.

  3. Potwierdź działającą konfigurację

    nginx -T wypisuje konfigurację, którą nginx faktycznie wczytał. docker compose exec webserver nginx -T | grep -n buffer musi pokazać nowe wartości na oczekiwanym poziomie. fastcgi_buffer_size w zagnieżdżonym location nadpisuje ustawienie z server lub http.

  4. Powtórz żądanie, które zawodziło

    Ten sam adres i te same ciasteczka co wcześniej; oczekuj 200 i braku nowej linii „too big header” w logach obu warstw.

⚠️ Uwaga: W Dockerze plik konfiguracyjny zamontowany osobno (./default.conf:/etc/nginx/conf.d/default.conf) jest związany z i-węzłem pliku. Narzędzia, które zapisują zmiany jako nowy plik i podmieniają nazwę, na przykład sed -i, zostawiają kontener ze starą wersją: w naszym teście nginx -t i reload się powiodły, a w kontenerze nadal nie było linii z buforami. Sprawdź to przez nginx -T i zrestartuj kontener (docker compose restart webserver), jeśli zmiany brakuje.

Ta sama poprawka w NetSendo

NetSendo, samodzielnie hostowana platforma do e-mail marketingu zbudowana na Laravelu, trafiła na ten błąd w edytorze wiadomości i naprawiła go z obu stron w wersji 2.2.1 (7 listopada 2026). Według changeloga pełne wczytanie edytora kończyło się 502, bo nagłówek Link wymieniał około 27 chunków i razem z ciasteczkami przekraczał 4-kilobajtowy bufor FastCGI; podsumowanie znajdziesz we wpisie o wydaniu 2.2.1.

  • Aplikacja używa teraz AddLinkHeadersForPreloadedAssets::using(8), co według changeloga utrzymuje nagłówki każdej strony na poziomie około 2 KB. To jest w obrazie Dockera.
  • docker/nginx/default.conf ustawia teraz fastcgi_buffer_size 32k i fastcgi_buffers 16 16k. Istniejące instalacje zachowują swoją kopię tego pliku, dopóki jej nie podmienią, więc po aktualizacji porównaj ją z aktualną wersją w repozytorium.
  • Sesje domyślnie trzymane są w Redisie (SESSION_DRIVER=redis w .env.example), więc ciasteczko sesji zawiera tylko identyfikator.
  • Reverse proxy na hoście opisane w dokumentacji konfiguracji używa domyślnych buforów proxy nginx. Przy nagłówkach rzędu 2 KB to wystarcza; jeśli w jego logu pojawi się „too big header”, dodaj trzy pokazane wyżej linie proxy_.

Inne 502 po aktualizacji NetSendo, z „connect() failed (111: Connection refused)” w logu, wynikało z nieaktualnego adresu kontenera i zostało naprawione w wersji 2.11.1. Nowe instalacje prowadzi szybki start.

🎯 Porady eksperta

1
Najpierw przeczytaj pole upstream

fastcgi:// albo http:// w linii logu mówi, którą rodzinę dyrektyw zmieniać, zanim czegokolwiek dotkniesz.

2
Mierz z zalogowaną sesją

Anonimowe żądania często niosą połowę ciasteczek. Skopiuj ciasteczko sesji z przeglądarki i powtórz pomiar curlem z -b.

3
Po każdej zmianie obserwuj oba logi

Naprawa wewnętrznego nginx przenosi 502 na zewnętrzne proxy. Podczas testów śledź logi błędów obu warstw.

4
Alarmuj o rozmiarze nagłówków

Dodaj do monitoringu pomiar %{size_header} najcięższej strony z alarmem powyżej około 75% bufora, żeby nowe ciasteczko albo większy bundle nie zaskoczyły Cię na produkcji.

Najczęściej zadawane pytania

Co powoduje błąd upstream sent too big header w nginx?

Upstream (PHP-FPM, serwer aplikacji albo kolejne proxy) wysłał nagłówki odpowiedzi większe niż bufor, w który nginx je wczytuje, domyślnie jedna strona pamięci, czyli 4 KB. Najczęściej winne są duże lub liczne ciasteczka, sesje trzymane w ciasteczku i długie nagłówki Link z preloadem.

Zmienić fastcgi_buffer_size czy proxy_buffer_size?

Sprawdź pole upstream w linii logu. fastcgi:// oznacza, że nginx rozmawia z PHP-FPM, więc zmieniasz fastcgi_buffer_size i fastcgi_buffers; http:// oznacza proxy, więc zmieniasz proxy_buffer_size, proxy_buffers i proxy_busy_buffers_size.

Jaka wartość proxy_buffer_size jest bezpieczna?

32k wystarcza prawie każdej aplikacji, razem z proxy_buffers 8 16k i proxy_busy_buffers_size 64k. Najpierw zmierz rzeczywiste nagłówki; jeśli potrzebujesz 64k lub więcej, popraw raczej aplikację.

Dlaczego nginx -t zgłasza błąd po zwiększeniu proxy_buffer_size?

Większy bufor nagłówków podnosi też domyślne proxy_busy_buffers_size, które musi być mniejsze niż suma proxy_buffers minus jeden bufor. Zwiększ jednocześnie proxy_buffers, na przykład do 8 16k.

Czy proxy_buffering off naprawia upstream sent too big header?

Nie. Nawet z wyłączonym buforowaniem nginx wczytuje nagłówki odpowiedzi do bufora o rozmiarze proxy_buffer_size, więc limit nagłówków się nie zmienia.

Źródła

E-mail marketing na Twoim własnym serwerze

NetSendo instaluje się przez Docker Compose i ma w konfiguracji opisane wyżej ustawienia nginx.

#nginx#php-fpm#laravel#docker#troubleshooting
Udostępnij