nginx 502: upstream sent too big header while reading response header

What’s actually happening

The browser gets a 502 Bad Gateway, but PHP-FPM is up and most pages work. It is the specific responses with oversized headers that break, often after a login or on a page that sets many cookies. nginx reads the upstream headers into a fixed buffer; when they do not fit, it gives up and returns 502. The error.log line names the exact request and upstream socket.

Common causes

• A large Set-Cookie header, frequently a fat session or a framework that serializes too much into the cookie.
• Several cookies set at once (session, CSRF, analytics, A/B flags) whose combined size exceeds fastcgi_buffer_size.
• Big auth headers, like a long JWT or SAML/OIDC token echoed back in the response.
• A debug or profiling header (verbose stack traces, an APM tool) appended in non-production.
• fastcgi_buffer_size left at its small default (4k/8k) while the app's real headers grew past it.

How to fix it

1. Confirm it is a header-size 502 from the logMatch the error.log line: 'upstream sent too big header while reading response header from upstream'. That string distinguishes this from a timeout or a crashed worker, which produce different 502 causes and different fixes.
2. Increase the FastCGI header buffersIn the server or location block set, for example, fastcgi_buffer_size 32k; and fastcgi_buffers 8 16k;. fastcgi_buffer_size covers the first chunk that holds the response headers, so it is the one that matters most here.
3. Bump busy buffers if nginx complainsIf a config test errors after the change, raise fastcgi_busy_buffers_size to match (for example 32k). For a reverse proxy upstream instead of FastCGI, the equivalents are proxy_buffer_size and proxy_buffers.
4. Test and reloadRun nginx -t, then reload nginx. Reproduce the request that 502'd (the login or the cookie-heavy page) and confirm it now returns 200.
5. Shrink the headers at the sourceBuffers treat the symptom. Also trim what PHP emits: store session data server-side instead of in the cookie, drop unused cookies, and strip debug headers in production so the response fits comfortably.