431 Request Header Fields Too Large
The combined size of the request headers exceeded the server's limit. In practice this is nearly always cookies: an accumulation of analytics, session and feature-flag cookies on one domain.
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.
# See how big the headers actually are
curl -sv https://example.com 2>&1 | awk '/^> /{n+=length($0)} END{print n" bytes"}'
# Server limits
# nginx: large_client_header_buffers 4 16k;
# Node: node --max-http-header-size=32768
# Apache: LimitRequestFieldSize 16384
# Real fix: stop storing state in cookies. Keep a session id and
# move the payload server-side.How to diagnose HTTP errors
HTTP status codes are a first classification, not a diagnosis. The essential split: 4xx means the request was wrong (fix the client), 5xx means the server failed to fulfil a valid request (fix the server). The subtlety is that reverse proxies and CDNs generate their own 5xx responses. A 502 or 504 from nginx tells you about nginx's relationship with the upstream, not about your application code.
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.
- Capture the full exchange with
curl -vorcurl -sD - -o /dev/null. Response headers frequently name the component that generated the error (Server:,Via:,X-Cache:). - Determine whether the response came from your application or from something in front of it. Add a unique header in your app and check whether it survives; if it is missing, a proxy answered.
- For 502/504, check the upstream directly, bypassing the proxy. If the upstream is healthy, the problem is proxy timeouts, buffer sizes, or DNS re-resolution.
- Follow redirects explicitly with
curl -ILto catch loops. A redirect loop is usually an HTTPS-terminating proxy that does not forwardX-Forwarded-Proto. - Correlate the request with server logs using a request ID. Guessing from the status code alone is the slowest way to debug HTTP.
Tools worth reaching for
curl -v / -ILbrowser devtools Network tabaccess logstcpdump / Wiresharkhttpstat
Authoritative references
Primary documentation for this error, worth reading before applying any fix in production.
Related HTTP errors
- 100-continue timeout / Expect: 100-continue stallsThe client sent Expect: 100-continue and is waiting before streaming the body, but the proxy…
- 400 Bad RequestThe server could not parse the request due to malformed syntax: bad JSON body, illegal…
- 401 UnauthorizedThe request requires authentication credentials. The client must authenticate to get the…
- 402 Payment RequiredReserved in the original HTTP specification and now used by many SaaS APIs to signal that the…
- 403 ForbiddenThe server understood the request but refuses to authorise it. Often due to insufficient…
- 404 Not FoundThe requested resource could not be found on the server. URL may be incorrect or resource was…
- 409 ConflictThe request conflicts with the current resource state. Typical causes include duplicate…
- 410 GoneThe resource was intentionally removed and is not expected to return. Unlike 404, 410 tells…
Browse other categories
- 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.
- Frontend 23Hydration mismatches, bundler resolution, layout shift and font loading.
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.