Nginx

Nginx "Upstream Sent Too Big Header While Reading Response Header From Upstream"

This error means the response headers sent by your backend exceed the buffer size Nginx has allocated to hold them — Nginx's default buffer sizes are conservative and work fine for typical responses, but backends returning unusually large headers (long cookies, extensive custom headers, verbose authentication tokens) can exceed them.

The Problem

A specific endpoint fails with a 500-level error, and Nginx's error log shows:

upstream sent too big header while reading response header from upstream, 
client: 203.0.113.5, server: example.com, request: "GET /api/data HTTP/1.1", 
upstream: "http://127.0.0.1:3000/api/data"

Other endpoints on the same backend might work fine, pointing specifically at something about this particular response's headers being unusually large, rather than a general proxy misconfiguration.

Why It Happens

Nginx allocates a fixed-size buffer to read response headers from the upstream before it can begin processing the response — by default, this is relatively small (often 4k or 8k, depending on platform and Nginx version), sized for typical header volumes. Common reasons a backend's headers exceed this:

  • An unusually large or numerous set of cookies being set in the response, particularly common with session-heavy applications or multiple third-party integrations each setting their own cookies
  • Extensive custom headers, such as detailed CORS headers, security headers, or application-specific metadata headers, especially when accumulated across multiple middleware layers each adding their own
  • A large JWT or authentication token included directly in a response header rather than in the response body
  • A misbehaving or misconfigured backend accidentally including unexpectedly large or duplicated header content, which is sometimes a genuine bug worth investigating on the backend side rather than assuming Nginx alone needs adjustment

The Fix

Increase the relevant buffer size directives in your Nginx configuration, in the http, server, or location block depending on how broadly you want the change to apply:

location /api/ {
    proxy_pass http://backend;
    proxy_buffer_size 16k;
    proxy_buffers 4 16k;
    proxy_busy_buffers_size 32k;
}

proxy_buffer_size specifically controls the buffer used for the initial part of the response (including headers), which is the most directly relevant setting for this exact error. proxy_buffers controls the number and size of buffers used for the rest of the response body, and proxy_busy_buffers_size limits how much buffer space can be simultaneously in use while sending a response to the client — increasing all three together, in reasonable proportion to each other, is the standard approach rather than adjusting just one in isolation.

Choose a buffer size comfortably larger than your actual header size, rather than the exact minimum — headers can grow over time as your application evolves (more cookies, more custom headers added later), and a buffer sized with reasonable headroom avoids needing to revisit this configuration every time header content grows slightly:

proxy_buffer_size 32k;  # generous headroom, rather than the bare minimum needed today

After adjusting, test and reload Nginx's configuration:

sudo nginx -t
sudo systemctl reload nginx

While increasing Nginx's buffer size resolves the immediate error, it's also worth reviewing whether the backend genuinely needs to send headers this large in the first place — particularly for cookies, since very large cookies also affect client-side performance and have their own size limits enforced by browsers independently of anything Nginx does. If the large headers stem from an accumulation of redundant or unnecessary data, trimming them at the source is often a better long-term fix than only increasing buffer sizes to accommodate ever-growing headers.

Still Not Working?

If increasing the proxy buffer sizes resolves the error for HTTP responses but you're also proxying FastCGI (PHP-FPM) or a different upstream protocol, confirm you're adjusting the correct, protocol-specific buffer directives, since Nginx has separate buffer settings for different upstream types that don't share configuration:

# For FastCGI upstreams specifically, not proxy_pass
fastcgi_buffer_size 16k;
fastcgi_buffers 4 16k;

Adjusting proxy_buffer_size has no effect on a FastCGI-proxied location using fastcgi_pass instead of proxy_pass — confirm which specific directive family matches how your particular location block is actually configured to reach its upstream, since each protocol type maintains entirely separate buffer configuration in Nginx.

You might also like