2026/11/17 10:15:32 [error] 1234#1234: *88 upstream sent too big header while reading response header from upstream, client: 203.0.113.7, server: example.com, request: "GET /account HTTP/1.1", upstream: "http://127.0.0.1:3000/account", host: "example.com"
Visitors see 502 Bad Gateway, often only on some pages (after login, on checkout, on pages that set many cookies).
Quick fix: the response headers from your backend are bigger than the buffer Nginx reserves for them. Give that buffer more room and reload:
location / {
proxy_pass http://127.0.0.1:3000;
proxy_buffer_size 16k;
proxy_buffers 8 16k;
proxy_busy_buffers_size 32k;
}
sudo nginx -t && sudo systemctl reload nginx
For PHP-FPM, use the fastcgi_ versions instead (section 3).
Nginx reads the backend's status line and headers into one buffer, set by proxy_buffer_size. By default it's one memory page: 4 KB or 8 KB depending on the system. When the headers don't fit, Nginx gives up on the response and returns 502.
1. Confirm the headers really are that big
Ask the backend directly, from the Nginx server, and measure what comes back:
# headers only, then their size in bytes
curl -s -D - -o /dev/null http://127.0.0.1:3000/account
curl -s -D - -o /dev/null http://127.0.0.1:3000/account | wc -c
If the page needs a logged-in session, copy your browser's cookie into the request:
curl -s -D - -o /dev/null -H 'Cookie: session=...' http://127.0.0.1:3000/account | wc -c
Anything above 4,000 bytes can hit the default buffer. Look at what makes it big. The usual suspects:
- Large
Set-Cookieheaders: a session stored entirely in the cookie, or a JWT with many claims. - Many cookies set at once: analytics, A/B testing and consent tools each adding their own.
- Long
Content-Security-PolicyorLink(preload) headers. - The same header sent twice by two layers of the app (middleware and framework).
2. proxy_pass: set the buffers so Nginx accepts them
Pick a proxy_buffer_size bigger than your largest headers (16k covers most apps, 32k the rest):
proxy_buffer_size 16k;
proxy_buffers 8 16k;
proxy_busy_buffers_size 32k;
The three settings have to agree, or nginx -t fails:
proxy_busy_buffers_sizemust be at least as large asproxy_buffer_sizeand one of theproxy_buffers.- It must also be smaller than all the
proxy_bufferstogether minus one buffer. With8 16k(128k in total), anything up to 112k is fine.
If you see this when testing the config, adjust proxy_busy_buffers_size:
nginx: [emerg] "proxy_busy_buffers_size" must be less than the size of all "proxy_buffers" minus one buffer
Put the settings in the location that proxies to the app, or in server or http to cover everything. Don't make them huge: these buffers are allocated per connection, so 1 MB buffers multiply quickly under load.
3. PHP-FPM, uWSGI and other backends
The same error appears with FastCGI (PHP-FPM, for example WordPress or Laravel). The message is the same, but the settings have a different prefix:
location ~ \.php$ {
fastcgi_pass unix:/run/php/php8.3-fpm.sock;
include fastcgi_params;
fastcgi_buffer_size 32k;
fastcgi_buffers 16 16k;
fastcgi_busy_buffers_size 32k;
}
For uWSGI (Python), use uwsgi_buffer_size and uwsgi_buffers. Changing the proxy_ settings has no effect on FastCGI or uWSGI locations.
Kubernetes ingress-nginx
On ingress-nginx, set it per Ingress with an annotation:
metadata:
annotations:
nginx.ingress.kubernetes.io/proxy-buffer-size: "16k"
4. Fix the cause, not just the buffer
Bigger buffers make the error go away, but headers that big also slow down every request and can hit limits elsewhere (load balancers, CDNs and browsers all have header size limits). Worth doing as well:
- Store session data on the server and keep only a short session ID in the cookie.
- Remove cookies you no longer need, especially ones set on every response.
- Set cookies on the paths that need them (
Path=/account) rather than on every page. - Check for duplicate headers after upgrading a framework or adding middleware.
5. Errors that look similar
| Log message | Meaning | Guide |
|---|---|---|
upstream sent too big header | Backend headers don't fit the buffer | This page |
upstream prematurely closed connection | Backend dropped the connection mid-response | Prematurely closed guide |
connect() failed (111: Connection refused) | Nothing listening at the upstream address | 111 guide |
upstream timed out (110: Connection timed out) | Backend too slow to answer | 110 guide |
client intended to send too large body (413) | The request is too big, not the response | 413 guide |
6. Know when it happens
This error often hits only some pages, such as after login, so a check on your homepage can miss it. Monitor the pages that matter too: a page that requires a session, or an API endpoint that sets cookies.
With Pingzo, an HTTP monitor calls each URL every 1 to 15 minutes depending on your plan. A 502 counts as a failed check, an incident opens when 3 of the last 5 checks fail, and alerts go to WhatsApp, Slack, Telegram, Discord or email. See how to monitor an Nginx web server.
Related guides
- Fix: nginx connect() failed (111: Connection refused) while connecting to upstream
- Nginx "upstream prematurely closed connection": how to fix
- Fix 504 Gateway Timeout with Nginx and PHP-FPM
Stop Finding Out About Outages from Angry Users
Get instant WhatsApp & Discord alerts the second your API, website, or server goes down. Setup in 30 seconds, with checks as often as every minute.