Australian cloud for business software — built and run in Sydney since 2002

NetLeverage
NetLeverage

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

Technical article
Troubleshooting

About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.

This error line in the nginx error log means the backend's response started with a status line and headers too large for the buffer nginx reads them into, so nginx treated the response as invalid. The visitor sees 502 Bad Gateway. Measure the header the backend sends, raise the first-response buffer in the location that serves the request, test the configuration and reload.

What the error means

nginx reads the first part of the response from the proxied server into one buffer. The proxy module documentation describes proxy_buffer_size as "the size of the buffer used for reading the first part of the response received from the proxied server. This part usually contains a small response header; if it exceeds the buffer size, the response is considered invalid." The default is 4k|8k: "the buffer size is equal to one memory page. This is either 4K or 8K, depending on a platform."

These log texts come from nginx's source code (release tag release-1.31.9), not from a documentation page. The source logs the fixed string "upstream sent too big header" when that buffer is full and the header is still incomplete. The source stores the action as the fixed string "reading response header from upstream", and the nginx log writer puts " while " in front of it (the format is " while %s"), which gives "while reading response header from upstream". The rest of the line (client, server, request, upstream, host) varies with the request. After the error, the source passes the request to the next-upstream logic with an invalid-header failure. In that logic the default status is 502 Bad Gateway. The proxy_next_upstream documentation gives the default error timeout, and describes invalid_header as "a server returned an empty or invalid response". The source passes the request to another server only if the failure type is listed in proxy_next_upstream; otherwise it ends the request with the 502 at once. So by default the visitor gets the 502 even when the upstream group has other servers.

Each protocol has its own directive for this buffer: proxy_buffer_size for proxy_pass, fastcgi_buffer_size for fastcgi_pass and uwsgi_buffer_size for uwsgi_pass. Each has the default 4k|8k and is valid in http, server and location. Raise the one that matches the location's *_pass directive. This error is about the response. A large request header from a client is a different limit, large_client_header_buffers, which defaults to 4 8k.

Likely causes

Cause What you see How to confirm
Response header larger than one buffer, often several large cookies The error line, 502 in the access log Save the backend's headers and count bytes (step 2 below); the count is above the buffer size
Buffer left at the platform default of one page No proxy_buffer_size in the location nginx -T shows no such directive for that location
Raised the wrong directive family No change after reload nginx -T shows fastcgi_pass or uwsgi_pass in the location, but a proxy_* directive was changed
Directive set in a different server or location block No change after reload The error line names the server and request; nginx -T shows which block serves it
New size breaks the buffer rules nginx -t fails The message mentions proxy_busy_buffers_size

Prove the cause before changing anything

All of these only read from the system, apart from two scratch files in /tmp that step 2 writes (it replaces them if they exist), provided the request you replay in step 2 is a GET of a page that has no side effects (a GET of the login page does not log anyone in; do not replay a form submission).

  1. Find the error line in the file named by the error_log directive. nginx -T prints the whole configuration, including that directive:
nginx -T

The line continues with details of the client, server, request and upstream. Note the request and the upstream address.

  1. Ask the backend directly, bypassing nginx, and save its headers. The curl manual says -D, --dump-header writes the received protocol headers to the named file. Use the request that failed, with the same cookies. NAME=VALUE is a cookie from the failing request; repeat -b 'NAME=VALUE' for each cookie:
curl -s -b 'NAME=VALUE' -D /tmp/headers.txt -o /tmp/body.out http://127.0.0.1:8080/login
wc -c /tmp/headers.txt

The byte count is the size of the status line and headers, within a few bytes. Compare it with the buffer: 4k is 4,096 bytes, 8k is 8,192 bytes. A good result is a count below the buffer. A bad result is a count above it.

  1. Read the configuration for the location and its *_pass:
nginx -T

Example (illustrative): app.example.com proxies to http://127.0.0.1:8080. After a login change, users get 502. The error log has the "upstream sent too big header" line for /login. The saved headers are 9,300 bytes. The location sets no proxy_buffer_size, and this host's page size is 8k, so the buffer is 8 x 1,024 = 8,192 bytes. 9,300 is 1,108 bytes over. A 16k buffer is 16 x 1,024 = 16,384 bytes, which leaves 16,384 - 9,300 = 7,084 bytes of headroom.

Fix

Raise the first-response buffer, with buffers that agree

The proxy source checks the combination when the configuration loads. The buffer that counts is the larger of proxy_buffer_size and one proxy_buffers buffer. proxy_busy_buffers_size defaults to twice that. It must be at least that size, and no more than the size of all proxy_buffers minus one buffer. Otherwise nginx refuses the configuration with a message naming proxy_busy_buffers_size.

Check the arithmetic for proxy_buffer_size 16k; with proxy_buffers 4 16k;. The larger size is 16k. The default busy size is 2 x 16k = 32k. The upper limit is (4 - 1) x 16k = 48k. 32k fits between 16k and 48k, so the pair passes.

Raising only proxy_buffer_size to 16k while proxy_buffers is the default 8 4k fails on a host with 4k pages. The larger size is 16k, the default busy size is 32k, and the upper limit is (8 - 1) x 4k = 28k. 32k is above 28k. On an 8k-page host the limit is 7 x 8k = 56k and it passes. Setting both directives avoids depending on the page size.

The proxy buffers apply per connection. The documentation says proxy_buffers sets "the number and size of the buffers used for reading a response from the proxied server, for a single connection." Larger values use more memory when many connections are busy.

Use the configuration file that contains your location (nginx -T dumps the configuration files, so you can find it there); the commands below use the example's path, so put your own path in the save and undo commands. First save the current file outside the directory nginx includes:

cp -p /etc/nginx/conf.d/app.example.com.conf /root/app.example.com.conf.2026-11-22

Disruptive step: the next change ends with nginx -s reload, which starts new workers with the new configuration and shuts the old ones down gracefully. A configuration that fails the test must not be reloaded. Larger buffers also raise memory use per proxied connection.

In the location that contains proxy_pass, add the two directives, then test and reload:

proxy_buffer_size 16k;
proxy_buffers 4 16k;
nginx -t && nginx -s reload

The command-line page says -t tests the configuration file, checking "the configuration for correct syntax, and then tries to open files referred in the configuration". It describes reload as reloading the configuration, starting the new worker process and gracefully shutting down the old ones.

To undo it: put the saved file back under its original name, test it, then reload:

cp -p /root/app.example.com.conf.2026-11-22 /etc/nginx/conf.d/app.example.com.conf
nginx -t && nginx -s reload

A location that uses fastcgi_pass reads this buffer from fastcgi_buffer_size and fastcgi_buffers, and one that uses uwsgi_pass from uwsgi_buffer_size and uwsgi_buffers. Changing those directives follows the same steps as above: save the file, test with nginx -t, reload, and keep the saved copy to restore. Do not mix directive families in one location.

Make the header smaller at the source

If cookies are growing without limit, the lasting fix is in the application: fewer or smaller cookies, or session data kept on the server. The buffer only moves the point at which the next growth fails again.

Confirm the fix

  1. nginx -t reports the configuration file is valid.
  2. The request that failed now returns the page, not 502.
  3. No new "upstream sent too big header" line appears in the error log for that request.
  4. The headers saved from the backend are comfortably below the new buffer.

What to watch afterwards

  • Header size of login and session responses, measured with the same curl -D check after each application release.
  • 502 counts per location in the access log.
  • Memory use of nginx workers after raising buffers on a busy site.

Risks and limits

  • These commands have not been run or lab-tested.
  • With buffering off, the documentation still ties the data nginx receives at a time to proxy_buffer_size: the proxy documentation says that with proxy_buffering off, the maximum data nginx receives at a time "is set by the proxy_buffer_size directive". This suggests, but the page does not say, that turning buffering off does not avoid this error.
  • The buffer-size rules shown are for proxy_* directives, from nginx's source code at release tag release-1.31.9. Other releases can differ, and the FastCGI and uwsgi modules have their own directives. Always run nginx -t.
  • The page size, 4k or 8k, depends on the platform and is not shown by nginx's documentation.

Sources