Nginx: upstream sent too big header while reading response header

Nginx logs "upstream sent too big header while reading response header from upstream" when the response headers from the backend server exceed the configured buffer size in nginx.conf.

The full error appears in the Nginx error log as:

upstream sent too big header while reading response header from upstream, client: 10.20.30.40, server: example.com

When Nginx Produces This Error

Nginx produces the "upstream sent too big header" error when the total size of the HTTP response headers from the upstream server exceeds the buffer allocated by fastcgi_buffer_size or proxy_buffer_size. This triggers a 502 Bad Gateway response to the client.

Nginx also produces this error when the upstream application sets large cookies, long session tokens, or verbose custom headers. PHP applications that store session data in cookies or pass complex authentication tokens in headers are common triggers.

What Causes the "Upstream Sent Too Big Header" Error in Nginx

Nginx returns this error when fastcgi_buffer_size is too small for PHP-FPM response headers.The fastcgi_buffer_size directive controls the buffer that Nginx allocates for reading the first part of the upstream response, which contains the HTTP headers. The default value is 4k or 8k depending on the platform. Response headers that exceed this size cause the error.

Nginx returns this error when proxy_buffer_size is too small for proxied upstream response headers.The proxy_buffer_size directive serves the same purpose as fastcgi_buffer_size but applies to proxied connections using proxy_pass. Large headers from application servers behind a reverse proxy trigger the error when the buffer is undersized.

Nginx returns this error when the upstream application sends oversized Set-Cookie headers.Applications that store large amounts of data in cookies (session tokens, shopping cart data, authentication claims) can produce headers that exceed the default buffer size. Each Set-Cookie header adds to the total header size.

How to Fix the "Upstream Sent Too Big Header" Error in Nginx

1. Increase the buffer sizes in the nginx.conf server block. Adjust both the header buffer and the response body buffers to accommodate larger responses from the upstream server.

For PHP-FPM backends using fastcgi_pass:

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

For proxied backends using proxy_pass:

server {
    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_buffer_size 128k;
        proxy_buffers 4 256k;
        proxy_busy_buffers_size 256k;
    }
}

2. Test the nginx.conf configuration and reload Nginx:

sudo nginx -t
sudo systemctl reload nginx

How to Verify the Fix

Nginx stops logging "upstream sent too big header" errors and returns successful responses instead of 502 errors. Send a request to the affected endpoint:

curl -I http://example.com/

A 200 OK response confirms that the buffer sizes accommodate the response headers. Check the Nginx error log to verify no new "too big header" entries appear:

tail -20 /var/log/nginx/error.log

Edge Cases and Variations

Nginx returns "too big header" errors for specific pages only.Pages that set many cookies or include complex authentication headers produce larger response headers than static pages. Apply the increased buffer sizes in a location block that matches only the affected paths rather than globally.

Nginx returns "too big header" errors after enabling caching or session management.Server-side caching systems and session management libraries can inject additional headers into each response. Review the upstream application's headers to determine whether the headers can be reduced in size. Moving session data from cookies to server-side storage reduces header size.

Increasing buffers too much wastes memory under high traffic.Each active connection allocates the configured buffer size. Setting proxy_buffers 4 256k allocates up to 1 MB per connection. On a server handling 1,000 concurrent connections, this consumes 1 GB of memory for buffers alone. Increase buffers incrementally and monitor memory usage.

Related Nginx Errors

Nginx: 502 Bad Gateway-- The 502 error is the client-facing result of the "too big header" problem. The error log identifies the buffer overflow as the specific cause.

Nginx: 504 Gateway Timeout-- Large headers combined with slow upstream responses can produce both timeout and buffer errors depending on which limit Nginx reaches first.