Nginx 502 "Upstream Sent Too Big Header" — Buffers, Not the App

When a proxied app returns very large headers (big cookies, long auth tokens), Nginx's default response buffers overflow and it returns 502. The app logs look clean because the app did nothing wrong.

What you'll see

Root causes

Default proxy buffer sizes exceeded

proxy_buffer_size defaults to only 4k/8k. Frameworks that pile cookies/JWTs/admin-toolbars onto responses overflow it.

A single enormous cookie (often not yours)

Third-party scripts and old analytics cookies can bloat request cookies; the app echoes or expands them. Check the Set-Cookie sizes in the browser devtools.

Fix it

  1. Confirm the exact error in the nginx log
    sudo tail -20 /var/log/nginx/error.log | grep -i 'too big header'
  2. Raise the response header buffers
    # inside the proxying location/server:
# proxy_buffer_size 16k;
# proxy_buffers 8 16k;
# proxy_busy_buffers_size 24k;
  3. Validate and reload
    sudo nginx -t && sudo systemctl reload nginx
  4. Attack the source: trim cookie size if headers exceed ~32k
    # devtools → Application → Cookies: sort by size, delete abandoned mega-cookies

Field note

Buffers must be sized per platform: 16k buffers must exist in multiples that satisfy your page size — if nginx -t complains, adjust powers of two. FastCGI variants of the same problem use fastcgi_buffer_size / fastcgi_buffers.

Common questions

Why do only logged-in users hit this 502?

Session and auth cookies make their response headers large. Anonymous responses fit in default buffers; authenticated ones don't. Raising proxy_buffer_size fixes both.

Is raising buffers a performance risk?

No — these are small per-connection allocations (kilobytes). The real fix if headers exceed ~32k is shrinking the cookies, since many clients have their own header size limits.

Related fixes

Ship it right the first time

Our most-documented failures, packaged as ready-to-ship starter kits: Docker, Kubernetes, and Terraform.

Browse the template store →

One-time. Yours to modify. Instant download from the NinjaOps template store.