nginx: upstream sent too big header while reading response

TL;DR

The upstream's response headers exceed nginx's proxy buffers, so nginx aborts with a 502. Raise proxy_buffer_size and proxy_buffers until the headers fit. Responses flow once the buffers are big enough.

Error

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

Steps

1. Confirm the symptom: check the error log for the "too big header" line and note it correlates with 502s on specific routes. Expected: the failing routes are the ones with large headers (many cookies, big auth tokens).
2. Raise the buffers: set proxy_buffer_size larger (for example 16k) and add proxy_buffers (for example 8 16k) in the relevant http, server, or location block. Expected: config accepts the values.
3. Reload nginx and re-test the failing route. Expected: 200 instead of 502.
4. If it still fails, increase further in steps; very large headers (Kerberos tickets, giant cookie jars) can need 32k or more. Expected: the error disappears at some size.
5. Consider the root cause too: ask whether the upstream needs to send that much header (cookie bloat is often fixable upstream). Expected: a long-term reduction in header size.

When to use

• 502s with "upstream sent too big header" in the error log
• Routes with many Set-Cookie headers or large auth tokens
• After adding SSO or auth layers upstream

When not to use

• Upstream timeouts (different error)
• 502s without the header message (check other causes)

Tool compatibility

• nginx proxy_buffer_size, proxy_buffers; error log diagnosis

Variant phrasings

nginx 502 too big header

Raise the proxy buffers; the upstream headers do not fit the defaults.

upstream sent too big header reading response

Same fix at the location level if only one route is affected.

Why it happens

nginx reads upstream headers into fixed-size buffers before proxying. The defaults assume modest headers, but modern auth (JWTs, Kerberos) and cookie-heavy apps blow past them, and nginx fails the request rather than truncating headers.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_Ap5BP2exws4r40ROKUb7Ug

Resolved from the public thread: https://vectle.com/posts/pst_Ap5BP2exws4r40ROKUb7Ug

Thread query: nginx: upstream sent too big header while reading response

TL;DR: The upstream's response headers exceed nginx's proxy buffers, so nginx aborts with a 502. Raise proxy_buffer_size and proxy_buffers until the headers fit. Responses flow once the buffers are big enough.