nginx "upstream sent too big header" 502 Fix

When nginx proxies a request, it reads the start of the backend's response, meaning the status line and all headers, into a single buffer before it decides what to do. If those headers do not fit, nginx gives up and returns a 502 Bad Gateway to the visitor. The error log says:

2026/10/08 11:02:41 [error] 2210#2210: *981 upstream sent too big header while reading response header from upstream, client: 198.51.100.20, server: example.com, request: "GET /wp-admin/ HTTP/1.1", upstream: "fastcgi://unix:/run/php/php8.2-fpm.sock:", host: "example.com"

Note the scheme in the upstream: field. fastcgi:// means you tune fastcgi_buffer_size, http:// means proxy_buffer_size, uwsgi:// means uwsgi_buffer_size, and scgi:// means scgi_buffer_size. Tuning the wrong family is the most common reason a fix "does not work".

Why headers get that big

The buffer defaults to one memory page, which is 4 KB or 8 KB depending on the platform. Headers are normally a few hundred bytes. They grow past the limit when the backend sends:

• Many or very large Set-Cookie headers. A framework that stores session data in the cookie, or a plugin that sets a dozen tracking cookies, is a classic cause.
• A very long Location header on a redirect, such as one carrying a big query string.
• A large Content-Security-Policy, Link preload list, or debug headers. The Laravel debug bar, Symfony profiler tokens and some APM agents add many.
• Repeated headers caused by an application bug, for example a login loop setting a new cookie on every redirect.

Use the HTTP Header Checker or curl to see how large the response headers really are:

curl -s -o /dev/null -D - https://example.com/wp-admin/ | wc -c
curl -s -o /dev/null -D - https://example.com/wp-admin/ | head -n 40

If the number is above roughly 4000 bytes, you have found the cause. The Cookie Checker lists every cookie the site sets.

Fix for PHP-FPM (fastcgi)

Add the buffer directives where you pass requests to PHP. On Debian and Ubuntu that is usually a location ~ \.php$ block in a file under /etc/nginx/sites-available/; on RHEL-family systems look in /etc/nginx/conf.d/:

location ~ \.php$ {
    include fastcgi_params;
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    fastcgi_buffer_size 32k;
    fastcgi_buffers 16 16k;
    fastcgi_busy_buffers_size 32k;
}

fastcgi_buffer_size is the one that holds the response headers, and is the directive that actually fixes this error. The other two keep the buffer arithmetic consistent for the response body. The socket path varies: RHEL-family PHP-FPM often listens on /run/php-fpm/www.sock.

Fix for proxy_pass (Node, Python, another web server)

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

For a start, 16k covers most cases. If the error continues, double it, but past 64k you should stop and look at why the headers are so large. Keep the arithmetic consistent: proxy_busy_buffers_size must be at least as large as proxy_buffer_size and smaller than the total of all proxy_buffers minus one buffer, otherwise nginx -t rejects the config.

Apply and test

sudo nginx -t
sudo systemctl reload nginx

Then repeat the request that failed. Watch for the error line to stop appearing: sudo tail -f /var/log/nginx/error.log.

Fix the cause, not just the buffer

Bigger buffers are cheap, but headers that are bloated for no reason also cost bandwidth on every response and can break clients and CDNs with their own limits. A few quick wins:

1. Delete unused cookies and stop plugins that set per-visit cookies.
2. Store session data on the server (database, Redis) and send only a session ID.
3. Turn off debug toolbars and verbose headers in production.
4. Find redirect loops that keep adding cookies. The रीडायरेक्ट चेकर shows the chain.

The reverse problem, where the browser sends headers that are too large, has a separate error and fix. See nginx 400 Request Header Or Cookie Too Large.

Confirm and monitor

After the change, check the page with the HTTP स्टेटस चेकर. It should return the expected 200 or redirect rather than 502. The 502 was only occurring on responses with big headers, so also test the specific pages that broke, such as login and admin screens. An uptime monitor with a keyword check on a logged-out page catches regressions on public pages, though not on pages behind login.

अगले कदम

• Review the full Fix 502 Bad Gateway checklist.
• Inspect response headers with the HTTP Header Checker.
• Audit cookies with cookie flags explained.
• Tune related limits in nginx 502 and 504 timeout tuning.

सामान्य प्रश्न

Which directive fixes "upstream sent too big header"?

proxy_buffer_size for proxied HTTP backends, fastcgi_buffer_size for PHP-FPM, uwsgi_buffer_size for uWSGI and scgi_buffer_size for SCGI. Match the scheme shown in the upstream: field of the log line.

Is this the same as a 400 header too large error?

No. This one is about headers the backend sends to nginx. A 400 "Request Header Or Cookie Too Large" is about headers the browser sends, fixed with large_client_header_buffers.

How large should I set the buffer?

Start at 16k, check the real header size with curl, and raise it only as needed. Anything beyond 64k usually signals an application problem.

Why does it only fail for some users?

Cookies accumulate per user, so users with long sessions or many cookies hit the limit first. Test with the account that fails.

यह पेज सामान्य जानकारी है, जिसे हमारी संपादकीय टीम ने लिखा है और दस्तावेज़ीकरण बदलने पर अपडेट किया जाता है। सर्वर और प्रदाता अलग-अलग होते हैं, इसलिए बदलाव पहले सुरक्षित तरीके से जाँचें। देखें: संपादकीय नीति और अस्वीकरण.