nginx: upstream sent too big header while reading response header

Quick fix

Read the commands before running them. Anything that restarts a service, deletes data or changes permissions should be tried on a non-production system first.

# Increase the header buffers for proxied responses
proxy_buffer_size    16k;
proxy_buffers        8 16k;
proxy_busy_buffers_size 32k;

# For FastCGI backends
fastcgi_buffer_size 32k;
fastcgi_buffers     8 32k;

nginx -t && systemctl reload nginx

# Then find out why the headers are that large, usually cookie bloat.

How to diagnose Proxy errors

A proxy error tells you about the proxy's relationship with the upstream, not about the upstream's business logic. nginx's 502 means it could not get a valid response; 504 means the upstream did not answer in time; Envoy's flag codes (UH no healthy upstream, UF upstream connection failure, NR no route) are far more precise than the status code. Reading those flags is the fastest path to a diagnosis.

If the quick fix above does not resolve it, work through these steps. They apply to this whole class of error, not just to this one message, which is usually what saves the time.

1. Include upstream detail in the access log format: $upstream_addr, $upstream_status and $upstream_response_time in nginx turn a generic 502 into a specific one.
2. Bypass the proxy and call the upstream directly from the proxy host. If that works, the issue is proxy configuration: timeouts, buffers, DNS caching or TLS to the backend.
3. For Envoy, read the response flags in the access log rather than the status code. UH, UF, UO and NR each have distinct fixes.
4. Check that the proxy re-resolves DNS. nginx caches upstream IPs at startup by default, which breaks when backends move. Use a resolver directive with a variable upstream.
5. For header-size and body-size errors, raise the limit at every layer; CDN, load balancer and origin each enforce their own.

Tools worth reaching for

• nginx -T
• envoy access logs (response flags)
• haproxy -c -f
• curl --resolve
• traefik dashboard

Authoritative references

Primary documentation for this error, worth reading before applying any fix in production.

📖 nginx.org

Related Proxy errors

• Caddy upstream errorCaddy web server failed to connect to or receive response from upstream server.
• Cloudflare 520: Web server returns an unknown errorCloudflare reached the origin but received a response it could not parse: an empty reply, a…
• Cloudflare 522: Connection timed outCloudflare edge could not establish TCP handshake to your origin. Origin offline, blocked by…
• Cloudflare 524: A timeout occurredCloudflare connected to the origin but no response arrived within the proxy read timeout, 100…
• Cloudflare errorCloudflare CDN encountered an error, often related to origin server connectivity or SSL issues.
• Cloudflare Worker 1101 runtime errorWorker script threw an exception during execution. Common causes: undefined variables, failed…
• Envoy upstream resetEnvoy proxy received a reset from the upstream service before completing the request.
• HAProxy server errorHAProxy load balancer encountered an error with backend servers, often health check failures.

See all 17 Proxy errors →

Browse other categories

• HTTP 494xx client errors, 5xx server errors, redirects, headers and protocol problems.
• JavaScript 42npm resolution, async pitfalls, hydration, memory limits and runtime type…
• Database 41Connections, deadlocks, constraints, replication and memory limits.
• AI 35Rate limits, context windows, GPU memory and model-serving failures.
• Network 35Refused connections, timeouts, resets, MTU problems and port exhaustion.
• Python 35Imports, virtual environments, encoding, concurrency and dependency conflicts.
• Kubernetes 34CrashLoopBackOff, ImagePullBackOff, OOMKilled, RBAC, scheduling and storage.
• Docker 27Daemon connectivity, disk space, image pulls, ports and architecture mismatches.
• System 26Disk space, systemd units, file descriptors, OOM killer and scheduled jobs.
• Cloud 25IAM permissions, quotas, service limits and credential failures.
• Security 25JWT validation, CSRF, OAuth grants, SELinux, SSH host keys and CSP.
• TLS 24Untrusted authorities, expiry, hostname mismatch, chains and cipher negotiation.

Something missing or wrong?

This entry is maintained by hand. If the fix is out of date, incomplete, or you have a better one, email a correction and it will be reviewed.