Fix Nginx “upstream sent too big header” errors

This error usually means an upstream response header did not fit in the response-header buffer for the module handling the request. Inspect large Set-Cookie, Location, or custom headers first, then size the relevant buffer to the response you actually need to support.

Recognize the failure

upstream sent too big header while reading response header from upstream,
client: 10.0.0.8, server: api.example.com, request: "GET /login HTTP/1.1",
upstream: "http://127.0.0.1:8080/login", host: "api.example.com"

The client commonly receives 502 Bad Gateway. This is an upstream response problem; client request-header limits are a different set of controls.

Adjust HTTP proxy buffers

In the affected server or location:

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

The header buffer must accommodate the required response header block. The sizes above illustrate a configuration, not a universal fix. Account for concurrent requests and validate the relationship between buffer settings.

sudo nginx -t
sudo systemctl reload nginx

Reload only if validation succeeds, and use the appropriate service mechanism for your deployment.

Use FastCGI directives for PHP-FPM

If the upstream uses FastCGI, the proxy directives do not control it:

location ~ \.php$ {
    # Buffer fragment only: retain your validated PHP routing configuration.
    fastcgi_pass unix:/run/php/php-fpm.sock;
    fastcgi_buffer_size 16k;
    fastcgi_buffers 8 16k;
}

This fragment is not a complete PHP configuration. It also needs correct FastCGI parameters, SCRIPT_FILENAME, and restrictions on which scripts may execute. Check inherited fastcgi_busy_buffers_size and related settings if validation reports a conflict.

Find the oversized header

Common causes include oversized cookie-based sessions, repeated Set-Cookie fields, debugging headers, or a long redirect destination. Consider moving excessive session data to server-side storage or reducing unnecessary response fields.

From an authorized host, measure the upstream response:

curl -sS -D - -o /dev/null http://127.0.0.1:8080/login | wc -c

Reproduce the affected Host header and authentication context. A different user session may produce a much smaller header. Keep captured cookies and credentials private. This command counts the dumped status/header output; interim responses can add another header block.

After reloading, retry the original request and inspect the error log. If Guance collects your Nginx logs, filter for this error around the change and compare upstream addresses. A lower 502 count alone does not establish which failure was fixed.

FAQ

Why not use a very large buffer immediately? Larger buffers increase per-request memory requirements. Choose measured headroom that fits the concurrency budget.

Why does the error persist? Confirm the request uses the server and location you changed, check inherited overrides, and measure its actual headers. Another kind of upstream failure can also produce 502.

Why does only one backend fail? Compare application versions, configuration, and session-dependent responses on each upstream. Request the same route with equivalent context before comparing sizes.

Related reading

• Apache RSA private-key configuration errors (Chinese)
• Python urllib certificate verification failures

Sources

This guide is based on the documentation below; the examples have not been tested against a live deployment.

• Nginx proxy module
• Nginx FastCGI module
• Guance Nginx integration