How to Resolve "Nginx Upstream Sent Too Big Header While Reading Response Header"

Nginx rejects a response from your backend because its headers exceed the buffer size Nginx allocated to read them. This is common with large cookies (especially session tokens or JWTs stored client-side), extensive custom headers, or authentication systems that pack a lot of data into response headers.

The Problem

A request that should succeed instead returns a 502, and the real cause is buried in the error log rather than in the response itself:

$ curl -i https://yourapp.com/login
HTTP/1.1 502 Bad Gateway

$ tail -5 /var/log/nginx/error.log
2026/08/07 18:14:02 [error] 8821#8821: *501 upstream sent too big header while reading
response header from upstream, client: 203.0.113.5, server: yourapp.com,
request: "POST /login HTTP/1.1", upstream: "http://127.0.0.1:3000/login"

Why It Happens

Nginx allocates a fixed-size buffer to read response headers from an upstream server before it starts streaming the body back to the client. By default, this buffer is quite small (matching the size of one memory page, typically 4KB or 8KB depending on the platform), which is enough for typical API responses but not always enough for responses carrying large cookies or many custom headers. This commonly happens when:

• An authentication system sets a large session cookie — JWTs with lots of embedded claims, or multiple large cookies set in a single response, can easily add up past the default buffer size.
• A backend framework adds verbose debug or tracing headers in a non-production-tuned configuration.
• Several separate Set-Cookie headers are combined in one response, each contributing to the total header size Nginx needs to buffer.
• A misbehaving upstream is sending malformed or excessively repeated headers due to an application bug rather than a legitimate need for more space.

The Fix

Raise the relevant buffer directives in the location or http block handling the affected requests:

location /login {
    proxy_pass http://127.0.0.1:3000;
    proxy_buffer_size 16k;
    proxy_buffers 4 16k;
    proxy_busy_buffers_size 32k;
}

proxy_buffer_size controls the buffer for the initial part of the response (headers), while proxy_buffers handles the body — increasing both gives Nginx enough room for large headers without truncating or rejecting the response. Test and reload:

sudo nginx -t
sudo systemctl reload nginx

If the issue is specifically FastCGI (PHP-FPM) rather than a proxied HTTP backend, the equivalent directives use the fastcgi_ prefix instead:

location ~ \.php$ {
    fastcgi_buffer_size 16k;
    fastcgi_buffers 4 16k;
}

While raising the buffer size resolves the immediate error, it's also worth investigating whether the response actually needs to carry that much header data. Oversized cookies in particular are often a sign of storing more in the cookie than necessary — consider moving large session payloads server-side (a session store keyed by a small opaque ID) instead of round-tripping the full payload in every request and response:

# Instead of a large JWT in a cookie on every request
Set-Cookie: session=eyJhbGc...(2KB of claims)...

# Consider a small session ID referencing server-side state
Set-Cookie: session_id=a1b2c3d4e5f6

Still Not Working?

If raising the buffer sizes doesn't resolve it, or you find yourself needing an unreasonably large buffer to accommodate the response, check whether the backend is genuinely misbehaving rather than just sending legitimately large data — inspect the actual raw response headers directly from the backend, bypassing Nginx, to see exactly what's being sent:

curl -i http://127.0.0.1:3000/login | head -c 2000

If you see duplicate or repeated headers, an unusually verbose stack trace accidentally included in headers, or clearly malformed content, the real fix is in the backend application code generating the response, not in continuing to raise Nginx's buffer limits to accommodate a bug.

It's also worth checking whether this error appears consistently for every user or only intermittently for a subset, since that distinction points at very different root causes. If it's consistent and predictable — always on login, always for the same endpoint — a fixed buffer increase as shown above is the right permanent fix. But if it's intermittent, appearing only for some users and not others, that's often a sign that certain user accounts are accumulating an unusually large number of roles, permissions, or claims that get serialized into the auth cookie or header, growing it well past what a typical user's session needs:

# Check header size across different real user sessions to spot the pattern
curl -s -D - -o /dev/null http://127.0.0.1:3000/login -H "Cookie: session=$TOKEN" | wc -c

If you find specific accounts driving unusually large headers, that's worth addressing at the application level — trimming unnecessary claims from the token, or moving to a reference-based session as described above — rather than continuing to raise Nginx's buffers indefinitely to accommodate a small number of outlier accounts.