Fix: upstream sent too big header while reading response header from upstream

This Nginx error log line means the backend responded, but its HTTP response headers did not fit in the buffer Nginx allocates for reading them. Nginx gives up on the response and serves the client a 502, so from the outside it looks like the backend is down when it is actually answering fine. The usual culprit is a huge cookie or an oversized JWT riding in a Set-Cookie header.

upstream sent too big header while reading response header from upstream

What this error means

When Nginx proxies a request, it reads the upstream response headers into a single buffer controlled by proxy_buffer_size (default 4k or 8k depending on platform, matching one memory page). If the status line plus all response headers exceed that buffer, Nginx cannot finish parsing the response, logs this error, and returns 502 Bad Gateway to the client. The body never even enters the picture; this is purely about header volume.

Because header size varies per user (cookies being the biggest variable), the error is typically intermittent, which makes it look like flaky infrastructure rather than what it is: a deterministic size check failing for specific sessions.

Common causes

• Large session cookies, often a framework storing serialized session state client side instead of a session ID.
• A JWT with many claims or embedded permissions stored in a cookie and echoed back in Set-Cookie.
• Many Set-Cookie headers stacked in one response, common with tracking, A/B testing, and consent tooling.
• Verbose framework or security headers, such as long Content-Security-Policy values plus debugging headers.
• OAuth or SSO flows that round-trip state through headers during the callback.
• The same failure over FastCGI to PHP-FPM, governed by fastcgi_buffer_size rather than the proxy directives.

How to fix it

STABILIZE first. Raise the proxy buffer sizes and reload Nginx. This is a safe, low-risk change that restores service for the affected users immediately.

1. Confirm the error and identify which upstream and URLs trigger it.

grep "too big header" /var/log/nginx/error.log | tail -20

2. Measure the actual response headers from the upstream directly, bypassing Nginx, for a request that fails. Use a real session cookie from an affected user if you can reproduce it.

curl -s -o /dev/null -D - http://127.0.0.1:3000/account -H "Cookie: session=..." | wc -c

DIAGNOSE with that number. If the headers total more than 4096 bytes you have found the trigger, and the header dump shows you exactly which header carries the weight. Nine times out of ten it is one giant cookie.

FIX in two moves. First, size the buffers so legitimate responses fit:

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

nginx -t && nginx -s reload

Note that proxy_busy_buffers_size must be at least as large as proxy_buffer_size and smaller than the total of proxy_buffers minus one buffer, or nginx -t will reject the config. For PHP-FPM, apply the same change to fastcgi_buffer_size and fastcgi_buffers.

Second, fix the header at the source. Move server-side session state out of the cookie and store only a session ID. Trim JWT claims to what the client actually needs. Deduplicate Set-Cookie headers emitted by middleware. Headers are sent on every request and response, so a 12 KB cookie is a per-request tax on every user, not just a buffer problem.

How to prevent it

• Set a header size budget: keep total response headers under 8 KB and alert in staging when a response exceeds it.
• Store session state server side (Redis, database) and put only an opaque ID in the cookie.
• Keep JWTs lean; claims that are only needed server side should be looked up, not embedded.
• Review third-party scripts and middleware that add cookies, and cap their number and size.
• Keep proxy_buffer_size explicitly set in your config so a platform default change never surprises you.

When to call a senior engineer

Call for help when the error persists after raising buffers (which usually means an SSO or gateway layer is inflating headers between hops), when the oversized cookie is load-bearing session state that cannot simply be trimmed, or when intermittent 502s continue and you cannot tie them to specific sessions. Erzon engineers can capture and diff the exact headers at each hop, redesign session storage so cookies stay small, and size every buffer in the chain so the 502s stop for good.