Fix Nginx Upstream Sent Too Big Header Error (2026)

Nginx is refusing to proxy requests because an upstream server is sending back a response with a header that’s too large for Nginx to handle.

Common Causes and Fixes

large_client_header_buffers is too small: This is the most frequent culprit. Nginx uses these buffers to store client request headers. If an upstream response is passed through Nginx and contains a large header (e.g., Set-Cookie with many domains, or a custom header), Nginx might try to buffer it as if it were a client request header, leading to this error.
- Diagnosis: Check your nginx.conf or relevant site configuration file for the large_client_header_buffers directive.
- Fix: Increase the number and size of buffers. A common starting point is:
```
large_client_header_buffers 4 16k;
```
  If you suspect the upstream is sending very large headers, you might need to go higher, like:
```
large_client_header_buffers 4 32k;
```
  or even:
```
large_client_header_buffers 8 32k;
```
- Why it works: This directive tells Nginx to allocate more memory for buffering incoming headers. While the error message mentions "upstream," Nginx’s internal logic can sometimes misinterpret large response headers as client request headers when proxying, especially if the response is very large. This increased buffer size accommodates those larger headers.
proxy_buffer_size and proxy_buffers are too small: These directives control the buffering of the response from the upstream server itself. If the upstream sends a response with a very large header before the body, and Nginx’s initial buffer for the response header is insufficient, it can manifest this error.
- Diagnosis: Look for proxy_buffer_size and proxy_buffers in your location block that uses proxy_pass.
- Fix: Increase proxy_buffer_size and potentially the number of proxy_buffers.
```
proxy_buffer_size 16k;
proxy_buffers 8 16k;
```
  For very large headers, consider:
```
proxy_buffer_size 32k;
proxy_buffers 16 32k;
```
- Why it works: proxy_buffer_size sets the size of the first buffer used for reading the response from the upstream. proxy_buffers defines the number and size of subsequent buffers. Increasing these allows Nginx to accept larger response headers from the upstream without hitting its limits.
proxy_busy_buffers_size is too small: This limits the total size of busy buffers used for one request. If Nginx is processing a response with multiple large headers, and the combined size exceeds this limit, it can also trigger the "sent too big header" error, even if individual buffers are sufficient.
- Diagnosis: Check for proxy_busy_buffers_size in your location block.
- Fix: Increase proxy_busy_buffers_size. It’s often recommended to set it to be at least twice the size of proxy_buffer_size to allow for concurrent buffering.
```
proxy_busy_buffers_size 32k;
```
  If you increased proxy_buffer_size to 32k, you might set it to 64k:
```
proxy_busy_buffers_size 64k;
```
- Why it works: This directive controls the maximum amount of memory that can be occupied by busy buffers for a single client connection. By increasing it, you give Nginx more headroom to accumulate header data from the upstream response before it flags the size as excessive.
Upstream Server is Misconfigured or Sending Excessively Large Headers: The problem might not be Nginx’s limits, but rather the upstream server generating a response with an absurdly large header. This could be due to application logic generating many cookies, long authentication tokens, or excessively verbose custom headers.
- Diagnosis: Temporarily increase Nginx buffer sizes significantly (e.g., large_client_header_buffers 8 128k;, proxy_buffer_size 128k;, proxy_buffers 16 128k;, proxy_busy_buffers_size 256k;). If the request then succeeds, inspect the actual response headers from your upstream server using tools like curl -I <your_upstream_url> or by logging them in Nginx. Look for headers like Set-Cookie, X- headers, or others that are unusually long or numerous.
- Fix: On the upstream server, investigate and reduce the size of the headers being sent. This might involve:
  - Optimizing cookie generation (e.g., removing unnecessary domains, reducing data stored).
  - Trimming custom headers.
  - Ensuring the application isn’t inadvertently appending large amounts of data to headers.
- Why it works: The root cause is addressed by making the upstream adhere to reasonable header sizes, rather than Nginx trying to accommodate an anomaly.
client_header_buffer_size is too small (less common for this specific error, but related): While the error explicitly mentions "upstream," Nginx’s internal mechanisms can sometimes lead to confusion if the initial client header buffer is too small and the request is then proxied. If Nginx cannot even parse the initial client request headers properly, it might lead to downstream issues that manifest with proxy errors.
- Diagnosis: Check client_header_buffer_size in your http block.
- Fix: Increase it. The default is usually 1k.
```
client_header_buffer_size 2k;
```
  or
```
client_header_buffer_size 4k;
```
- Why it works: Ensures Nginx can correctly parse the headers of the incoming request from the client, which is a prerequisite for successful proxying. If the client request headers themselves are large, this buffer needs to be adequate.
Nginx Version or Specific Module Interaction: In rare cases, a bug in a specific Nginx version or an interaction with a third-party module could cause incorrect handling of large headers during proxying.
- Diagnosis: Check your Nginx version (nginx -v). Search Nginx bug trackers or module documentation for known issues related to header buffering or proxying.
- Fix: Upgrade Nginx to the latest stable version. If using third-party modules, ensure they are compatible and up-to-date. Sometimes, disabling a suspected module temporarily can help isolate the issue.
- Why it works: Addresses potential software defects by using a more robust or fixed version of the code.

After applying any configuration changes, remember to test your Nginx configuration (nginx -t) and reload Nginx (sudo systemctl reload nginx or sudo service nginx reload).

The next error you’ll likely encounter if you’ve fixed this, but haven’t addressed the upstream’s actual data limits, is 502 Bad Gateway if the upstream crashes or 504 Gateway Timeout if the upstream is too slow to respond after Nginx finally starts receiving data.