Nginx 502 „upstream sent too big header“ beheben

Nginx schreibt „upstream sent too big header while reading response header from upstream“ ins Fehlerlog und antwortet mit 502 Bad Gateway, wenn die Response-Header deiner Anwendung (PHP-FPM, ein Container, ein weiterer Proxy) nicht in den einen Puffer passen, den nginx dafür reserviert. Standardmäßig ist dieser Puffer eine Speicherseite groß, auf den meisten Linux-Servern 4 KB. Die Lösung: Erhöhe fastcgi_buffer_size (für PHP-FPM) oder proxy_buffer_size (für einen Reverse Proxy) auf genau der nginx-Ebene, die den Fehler geloggt hat, und finde danach heraus, warum die Header so groß geworden sind.
curl -s -o /dev/null -w '%{size_header}\n'; alles um 4 KB scheitert mit den Standardwerten. Wo nginx mit PHP-FPM spricht, setzt du fastcgi_buffer_size 32k; fastcgi_buffers 16 16k;, wo nginx an einen anderen Server weiterleitet, proxy_buffer_size 32k; proxy_buffers 8 16k; proxy_busy_buffers_size 64k;, dann nginx -t und Reload. Bei zwei nginx-Ebenen (Proxy auf dem Host vor einem Container) änderst du die, in deren Log der Fehler steht, und nach der Korrektur der inneren scheitert meist als Nächstes die äußere. Danach verkleinerst du die Header an der Quelle: Sessions im Cookie und Laravels Link-Preload-Header sind die üblichen Ursachen.Was bedeutet „upstream sent too big header“?
Der Upstream-Server hat Statuszeile und Header geschickt, die größer sind als der Puffer, in den nginx den Anfang der Antwort liest. Nginx hält die Antwort deshalb für ungültig und liefert dem Client 502. „Upstream“ ist alles, wohin nginx den Request weiterreicht: PHP-FPM per FastCGI, ein Anwendungsserver per HTTP oder ein weiterer nginx.
Die Dokumentation des FastCGI-Moduls beschreibt es direkt: Der Puffer für den ersten Teil der Antwort enthält normalerweise einen kleinen Response-Header, und wenn der Header größer ist, gilt die Antwort als ungültig. Standard ist eine Speicherseite, also 4K oder 8K je nach Plattform. Das Proxy-Modul hat dieselbe Regel für proxy_buffer_size. Unter Linux auf x86-64 ist eine Seite 4.096 Byte groß; prüfen kannst du das mit getconf PAGESIZE.
Ein einzelner Puffer pro Verbindung (fastcgi_buffer_size, proxy_buffer_size und die Entsprechungen uwsgi_, scgi_ und grpc_), der Statuszeile und alle Response-Header auf einmal fassen muss. Der Body darf in weitere Puffer oder eine temporäre Datei ausweichen, die Header nicht.
Drei Dinge ist dieser Fehler nicht. Er betrifft nicht den Request: Zu große Request-Header oder Cookies vom Browser ergeben 400 „Request Header Or Cookie Too Large“, dafür ist large_client_header_buffers zuständig. Er betrifft nicht den Body: Eine 5 MB große HTML-Seite passt problemlos durch denselben 4-KB-Header-Puffer. Und Pufferung abschalten hilft nicht: Auch mit proxy_buffering off liest nginx die Header in einen Puffer der Größe proxy_buffer_size.
Wie bestätigst du, dass es dieser Fehler ist?
Such die genaue Zeile im nginx-Fehlerlog des Servers, der die 502 geliefert hat, und miss dann die Response-Header der betroffenen URL mit curl. Ein 502 hat mehrere mögliche Ursachen, und die Logzeile unterscheidet sie.
# nginx direkt auf dem Host
sudo grep "too big header" /var/log/nginx/error.log | tail -n 3
# nginx in Docker (das offizielle Image schreibt das Fehlerlog nach stderr)
docker compose logs webserver 2>&1 | grep "too big header" | tail -n 3
Diese Zeile kam aus einem unveränderten nginx:alpine-Container (nginx 1.31.8) vor php:8.3-fpm-alpine, als ein PHP-Skript 4 KB Set-Cookie-Header schickte:
[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"
Achte auf das Feld upstream:. fastcgi:// heißt, dieser nginx spricht mit PHP-FPM und braucht die fastcgi_-Direktiven; http:// heißt, er leitet an einen anderen HTTP-Server weiter und braucht die proxy_-Direktiven.
Header messen
Der Browser zeigt dir die Header einer 502 nicht, weil nginx sie verworfen hat. Frag das Backend direkt, an der fehlerhaften Ebene vorbei, und zähl die Bytes:
# Header-Bytes einer Antwort insgesamt (im HTTP/1-Format)
curl -s -o /dev/null -w '%{size_header}\n' http://127.0.0.1:8080/login
# die Header selbst, größte zuerst
curl -s -o /dev/null -D - http://127.0.0.1:8080/login | awk '{ print length($0), $1 }' | sort -rn | head
Nimm GET, nicht curl -I: Manche Anwendungen antworten auf HEAD mit anderen Headern. Wiederhole die Messung mit den Cookies einer eingeloggten Session (-b 'laravel_session=…'), denn die größten Header entstehen oft erst nach dem Login oder nur auf einer bestimmten Seite. Liegt die Summe nahe 4.096 Byte oder darüber, hast du die Ursache.
| Zeile im Fehlerlog | Status | Was sie meist bedeutet |
|---|---|---|
| upstream sent too big header while reading response header from upstream | 502 | Response-Header größer als *_buffer_size |
| connect() failed (111: Connection refused) while connecting to upstream | 502 | An der Upstream-Adresse lauscht nichts (Backend aus oder veraltete Container-IP) |
| upstream prematurely closed connection while reading response header from upstream | 502 | Der Backend-Prozess ist abgestürzt oder hat die Verbindung mitten im Request geschlossen |
| upstream timed out (110: Connection timed out) while reading response header from upstream | 504 | Backend zu langsam; ein Timeout-, kein Pufferproblem |
Stand: November 2026, nginx 1.31.8. Die ersten beiden Zeilen haben wir in unserer Testumgebung nachgestellt, die anderen sind Standardmeldungen von nginx.
Warum werden Response-Header so groß?
Fast immer durch eines von vier Dingen: Cookies, Link-Preload-Header, Tokens oder Debug-Header. Eine normale Antwort ohne sie liegt deutlich unter 1 KB, für 4 KB muss also etwas wachsen.
- Sessions im Cookie. Mit Laravels Session-Treiber
cookiewerden Sessions in sicheren, verschlüsselten Cookies gespeichert (Laravel-Dokumentation). Alles in der Session, auch Flash-Daten und alte Formulareingaben, geht verschlüsselt bei jeder Antwort alsSet-Cookiezurück. Verschlüsselung und Base64 machen das Cookie größer als die Daten selbst. Browser müssen nur „mindestens 4096 Byte pro Cookie“ annehmen (RFC 6265, Abschnitt 6.1), eine Cookie-Session allein kann also schon an den Standardpuffer von nginx heranreichen. - Viele Set-Cookie-Header. Session, CSRF-Token, „Angemeldet bleiben“, Consent, A/B-Tests und Analytics: Jedes Cookie ist ein eigener Header mit eigenen Attributen
Path,Expires,SameSiteundSecure. - Link-Preload-Header. Laravels Middleware
AddLinkHeadersForPreloadedAssetsschreibt jedes Skript und Stylesheet, das der Vite-Helper zum Preload markiert hat, in einen einzigenLink-Header (Framework-Quellcode). Laravels offizielle Starter Kits hängen diese Middleware an die Web-Gruppe (Vue Starter Kit). Eine Seite mit mehr als 25 Chunks und absoluten URLs ergibt einen Header von mehreren Kilobyte. - Tokens und Debug-Daten. JWTs in Cookies oder eigenen Headern, Content-Security-Policy-Header mit langen Domainlisten und Entwickler-Toolbars, die Daten in Headern übertragen.
Weil Cookies von der Session und Preload-Header von der Seite abhängen, trifft der Fehler meist nur einige URLs und nur einen Teil der Nutzer. „Klicken in der App geht, neu laden gibt 502“ ist ein typisches Zeichen für den Link-Header: Die Navigation innerhalb einer Single-Page-App lädt JSON, ein vollständiger Seitenaufruf liefert HTML mit allen vorab geladenen Chunks im Header.
fastcgi_buffer_size oder proxy_buffer_size: was änderst du?
Das Modul, das zum upstream: in der Logzeile passt: fastcgi_buffer_size, wo nginx Requests mit fastcgi_pass an PHP-FPM gibt, und proxy_buffer_size, wo er sie mit proxy_pass weiterleitet. Die jeweils andere Direktive zu ändern bewirkt nichts.
| Direktive | Verwendet mit | Standard (Byte) | Unser Wert |
|---|---|---|---|
fastcgi_buffer_size | fastcgi_pass (PHP-FPM) | 4k oder 8k (eine Seite) | 32k |
fastcgi_buffers | fastcgi_pass | 8 × 4k oder 8k | 16 16k |
fastcgi_busy_buffers_size | fastcgi_pass | 8k oder 16k | Standard, solange nginx -t nicht meckert |
proxy_buffer_size | proxy_pass (HTTP-Upstream) | 4k oder 8k (eine Seite) | 32k |
proxy_buffers | proxy_pass | 8 × 4k oder 8k | 8 16k |
proxy_busy_buffers_size | proxy_pass | 8k oder 16k | 64k |
Standardwerte aus der nginx-Dokumentation der Module FastCGI und Proxy, Stand: November 2026.
Für PHP-FPM:
location ~ \.php$ {
fastcgi_pass php:9000;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
# Response-Header bis 32 KB statt einer 4-KB-Seite
fastcgi_buffer_size 32k;
fastcgi_buffers 16 16k;
}
Für einen 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;
}
Warum nur die Puffergröße zu erhöhen an nginx -t scheitert
Setzt du nur proxy_buffer_size 16k (oder fastcgi_buffer_size 32k) und lässt *_buffers 8 4k auf Standard, verweigert der Konfigurationstest den Start. Wir bekamen genau das:
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
Der Grund steht in der Beschreibung von proxy_busy_buffers_size: Standardmäßig ist der Wert auf zwei Puffer aus proxy_buffer_size und proxy_buffers begrenzt. Hebst du den Header-Puffer auf 16k, steigt der Standard für „busy“ auf 32k, und das ist mehr als 8 × 4k = 32k Body-Puffer minus ein Puffer. Erhöhe proxy_buffers mit (8 16k geht durch), und wenn du proxy_busy_buffers_size explizit setzt, halte es unter der Summe von proxy_buffers minus einem Puffer: Bei 4 × 16k ging 32k durch, 64k scheiterte mit derselben Meldung. Das FastCGI-Modul meldet denselben Fehler mit fastcgi_-Namen. Beachte, dass die Meldung auf nginx.conf zeigt, nicht auf die Datei, die du bearbeitet hast.
Wie groß ist sicher?
Groß genug für deine gemessenen Header plus Reserve, mehr nicht. Die Puffer werden pro Verbindung belegt: der Header-Puffer bei jedem weitergeleiteten Request, die anderen, wenn der Body sie braucht. 32k reicht für jede vernünftige Anwendung mit viel Luft. Brauchst du 64k oder mehr, erzeugt etwas Header, mit denen auch Browser und CDNs Probleme bekommen, und die Korrektur gehört in die Anwendung.
Zwei nginx-Ebenen: welche musst du ändern?
Die Ebene, in deren Fehlerlog die Zeile steht. In einem typischen Docker-Setup terminiert nginx auf dem Host (etwa auf einem Hetzner- oder IONOS-Server) HTTPS und leitet an einen nginx-Container weiter, der PHP-Requests an PHP-FPM gibt. Beide Ebenen haben ihre eigenen 4 KB Standard, und beide antworten mit 502.
Wir haben diese Kette aus unveränderten Images gebaut (Proxy wie auf dem Host → nginx:alpine → php:8.3-fpm-alpine) und das PHP-Skript immer mehr Set-Cookie-Header à 1 KB schicken lassen:
| Zusätzliche Header (KB) | Innerer nginx, FastCGI-Standard | Innerer nginx, fastcgi_buffer_size 32k | Äußerer Proxy, Standard (innerer auf 32k) | Äußerer 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 |
Gemessen am 16. November 2026, nginx 1.31.8, PHP 8.3 FPM, Speicherseite 4.096 Byte. Eine Antwort mit 6 KB zusätzlichen Cookies hatte laut curl 6.346 Byte Header.
Daraus folgen zwei praktische Lehren. Erstens verschiebt die Korrektur der inneren Ebene den Fehler nach außen: Nach dem Vergrößern des FastCGI-Puffers scheiterten dieselben Requests am äußeren Proxy, mit upstream: "http://…" in dessen Log, und der Browser sah dieselbe 502. Zweitens reicht die äußere Ebene einfach weiter, was die innere liefert: Sind beide zu klein, steht der Fehler nur im inneren Log, bis die innere korrigiert ist. Prüf bei jedem Test beide Logs.
ℹ️ Hinweis: Load Balancer und CDNs vor nginx haben eigene Header-Limits, die du nicht immer ändern kannst. Ein weiterer Grund, die Header an der Quelle zu verkleinern, statt auf jeder Station die Puffer zu erhöhen.
Wie verkleinerst du die Header an der Quelle?
Speichere Sessions auf dem Server, schick weniger Preload-Links und pack keine Daten mehr in Cookies. Größere Puffer beseitigen die 502; kleinere Header machen jeden Request günstiger und halten dich von Limits weiter hinten in der Kette fern.
Sessions aus dem Cookie holen
Stell in Laravel den Session-Treiber von cookie auf redis oder database um. Der Browser hält dann nur noch die Session-ID.
# .env
SESSION_DRIVER=redis # oder: database (braucht die Tabelle sessions)
php artisan config:clear
Der Wechsel meldet alle einmal ab, weil die bestehenden Sessions im alten Speicher liegen. Beim Treiber database muss die Tabelle sessions existieren (php artisan make:session-table und php artisan migrate in Laravel-Versionen, die sie nicht mitbringen).
Link-Header begrenzen
Ab Laravel 12 nimmt die Middleware ein Limit an: AddLinkHeadersForPreloadedAssets::using(8) listet nur die ersten 8 Assets (Quellcode). Sonst ändert sich nichts: Die @vite-Direktive schreibt weiterhin für jeden Chunk ein <link rel="modulepreload"> ins HTML.
// bootstrap/app.php
use Illuminate\Http\Middleware\AddLinkHeadersForPreloadedAssets;
->withMiddleware(function (Middleware $middleware) {
$middleware->web(append: [
AddLinkHeadersForPreloadedAssets::using(8),
]);
})
In Laravel 10 und 11 hat die Middleware keine using()-Methode. Dort kannst du sie aus der Web-Gruppe entfernen (die Preload-Tags im HTML bleiben) oder das Framework aktualisieren.
Cookies prüfen
- Entferne Cookies, die niemand mehr liest, und setz nicht bei jeder Antwort dasselbe Cookie neu, wenn sich sein Wert nicht geändert hat.
- Halte Tokens möglichst aus Cookies heraus oder ihre Claims kurz; ein JWT mit Profildaten ist ein Header-Problem auf Abruf.
- Cookies von Drittanbieter-Skripten, die der Server nicht braucht, setzt du im Browser oder auf einer eigenen Subdomain.
✅ Vorteile der Korrektur an der Quelle
- Behebt alle Ebenen auf einmal, auch CDNs, die du nicht kontrollierst
- Kleinere Requests und Responses bei jedem Seitenaufruf
- Kein zusätzlicher Speicher pro Verbindung auf dem Proxy
❌ Zu beachten
- Ein Wechsel des Session-Treibers meldet Nutzer einmal ab
- Braucht ein Deployment, eine Pufferänderung nur einen Reload
- Cookies von Drittanbietern liegen eventuell außerhalb deiner Kontrolle
Wie setzt du die Änderung um und prüfst sie?
Konfiguration ändern, nginx -t ausführen, neu laden und den fehlgeschlagenen Request wiederholen, während du das Log beobachtest. Ein Reload übernimmt neue Einstellungen, ohne offene Verbindungen abzubrechen.
- Konfiguration testen
sudo nginx -tauf dem Host oderdocker compose exec webserver nginx -tim Container. Jedes[emerg]zuerst beheben. - Neu laden
sudo systemctl reload nginx(odersudo nginx -s reload); in Dockerdocker compose exec webserver nginx -s reload. - Laufende Konfiguration bestätigen
nginx -Tgibt die Konfiguration aus, die nginx tatsächlich geladen hat.docker compose exec webserver nginx -T | grep -n buffermuss deine neuen Werte auf der erwarteten Ebene zeigen. Einfastcgi_buffer_sizein einer verschachteltenlocationüberschreibt den Wert ausserveroderhttp. - Fehlgeschlagenen Request wiederholen
Gleiche URL, gleiche Cookies wie vorher; erwartet wird 200 und keine neue „too big header“-Zeile in den Logs beider Ebenen.
⚠️ Achtung: In Docker ist eine einzeln gemountete Konfigurationsdatei (./default.conf:/etc/nginx/conf.d/default.conf) an den Inode der Datei gebunden. Werkzeuge, die beim Speichern eine neue Datei schreiben und umbenennen, etwased -i, lassen den Container die alte Version lesen: In unserem Test liefennginx -tund Reload erfolgreich durch, während im Container noch keine Pufferzeilen standen. Prüf das mitnginx -Tund starte den Container neu (docker compose restart webserver), wenn die Änderung fehlt.
Dieselbe Korrektur in NetSendo
NetSendo, eine selbst gehostete E-Mail-Marketing-Plattform auf Laravel-Basis, stieß im Nachrichteneditor auf diesen Fehler und hat ihn in Version 2.2.1 (7. November 2026) an beiden Enden behoben. Laut Changelog antwortete ein vollständiger Aufruf des Editors mit 502, weil der Link-Header rund 27 Chunks auflistete und die Response-Header zusammen mit den Cookies über den 4-KB-FastCGI-Puffer von nginx trieb.
- Die Anwendung nutzt jetzt
AddLinkHeadersForPreloadedAssets::using(8), was laut Changelog die Header jeder Seite bei etwa 2 KB hält. Das steckt im Docker-Image. docker/nginx/default.confsetzt jetztfastcgi_buffer_size 32kundfastcgi_buffers 16 16k. Bestehende Installationen behalten ihre Kopie dieser Datei, bis sie sie ersetzen; vergleich sie nach einem Update mit der aktuellen Version im Repository.- Sessions liegen standardmäßig in Redis (
SESSION_DRIVER=redisin.env.example), das Session-Cookie enthält also nur eine ID. - Der Reverse Proxy auf dem Host aus der Konfigurationsdokumentation nutzt die Standard-Proxy-Puffer von nginx. Bei 2 KB Headern reicht das; zeigt sein Log doch einmal „too big header“, ergänze die drei
proxy_-Zeilen von oben.
Eine andere 502 nach einem NetSendo-Update, mit „connect() failed (111: Connection refused)“ im Log, kam von einer veralteten Container-Adresse und ist seit Version 2.11.1 behoben. Neue Installationen folgen dem Schnellstart.
🎯 Expertentipps
fastcgi:// oder http:// in der Logzeile sagt dir, welche Direktivenfamilie du ändern musst, bevor du irgendetwas anfasst.
Anonyme Requests tragen oft nur die Hälfte der Cookies. Kopier das Session-Cookie aus dem Browser und wiederhole die curl-Messung mit -b.
Die Korrektur des inneren nginx verschiebt die 502 zum äußeren Proxy. Verfolge beim Testen die Fehlerlogs beider Ebenen.
Nimm eine curl-Prüfung von %{size_header} für deine schwerste Seite ins Monitoring auf, mit Alarm ab etwa 75 % des Puffers, damit ein neues Cookie oder ein größeres Bundle dich nicht in Produktion überrascht.
Häufig gestellte Fragen
Was verursacht upstream sent too big header in nginx?
Der Upstream (PHP-FPM, ein Anwendungsserver oder ein weiterer Proxy) hat Response-Header geschickt, die größer sind als der Puffer, in den nginx sie liest, standardmäßig eine Speicherseite bzw. 4 KB. Typische Ursachen sind große oder viele Cookies, Sessions im Cookie und lange Link-Preload-Header.
Muss ich fastcgi_buffer_size oder proxy_buffer_size ändern?
Schau auf das Feld upstream in der Logzeile. fastcgi:// heißt, nginx spricht mit PHP-FPM, also änderst du fastcgi_buffer_size und fastcgi_buffers; http:// heißt Proxy, also proxy_buffer_size, proxy_buffers und proxy_busy_buffers_size.
Welcher Wert für proxy_buffer_size ist sicher?
32k reicht für fast jede Anwendung, zusammen mit proxy_buffers 8 16k und proxy_busy_buffers_size 64k. Miss zuerst deine echten Header; brauchst du 64k oder mehr, korrigiere lieber die Anwendung.
Warum scheitert nginx -t, nachdem ich proxy_buffer_size erhöht habe?
Ein größerer Header-Puffer erhöht auch den Standardwert von proxy_busy_buffers_size, der unter der Summe von proxy_buffers minus einem Puffer bleiben muss. Erhöhe proxy_buffers gleichzeitig, zum Beispiel auf 8 16k.
Hilft proxy_buffering off gegen upstream sent too big header?
Nein. Auch mit abgeschalteter Pufferung liest nginx die Response-Header in einen Puffer der Größe proxy_buffer_size, das Header-Limit bleibt also gleich.
Quellen
- nginx: ngx_http_fastcgi_module
- nginx: ngx_http_proxy_module
- nginx: large_client_header_buffers (ngx_http_core_module)
- Laravel framework: AddLinkHeadersForPreloadedAssets middleware (12.x)
- Laravel Vue starter kit: bootstrap/app.php
- Laravel documentation: HTTP Session
- RFC 6265: HTTP State Management Mechanism (section 6.1, limits)
- NetSendo CHANGELOG (2.2.1: message editor 502 fix)
E-Mail-Marketing auf deinem eigenen Server
NetSendo installierst du mit Docker Compose, die oben beschriebenen nginx-Einstellungen sind schon dabei.




