nginx: upstream sent too big header

1. About the error
2. Why do I see this error
3. Solution
4. Fix the root cause too

#About the error

The visitor gets a 502 Bad Gateway and the nginx error log explains why:

upstream sent too big header while reading response header from upstream

nginx reserves a fixed-size buffer for the response headers it reads back from your application (PHP-FPM or a proxied service). If the headers don't fit, nginx can't process the response and returns a 502.

#Why do I see this error

• Large cookies, especially a big session cookie or many cookies set at once.
• A long Set-Cookie from a fat session payload.
• Many or unusually large custom headers.
• A redirect with a very long Location URL.

It frequently appears right after login, when the session and its cookie grow.

#Solution

Increase the FastCGI buffer sizes so the headers fit. For a PHP-FPM app:

fastcgi_buffer_size 32k;
fastcgi_buffers 8 16k;
fastcgi_busy_buffers_size 64k;

For a proxied application (proxy_pass), the equivalents are:

proxy_buffer_size 32k;
proxy_buffers 8 16k;
proxy_busy_buffers_size 64k;

Put these in the relevant location or server block, then validate and reload:

nginx -t && systemctl reload nginx

#Fix the root cause too

Bigger buffers treat the symptom. If the headers are huge because you're storing a lot in the session (and therefore the cookie), trim it. In Laravel, keep large data server-side by using a non-cookie session driver such as redis or database rather than the cookie driver, so only a small session id travels in the header:

SESSION_DRIVER=redis

See Redis connection refused in Laravel if you switch to the Redis driver.