431 Request Header Fields Too Large
The server refuses to process the request because the HTTP headers are too large.
Meaning & Description
Common Causes
- Cookie bloat: An application set too many cookies or extremely large cookies without cleaning them up.
- Massive authentication tokens (like OAuth JWTs containing huge payload claims).
- Infinite redirect loops involving proxies that append an `X-Forwarded-For` header on every bounce.
How to fix a 431 error
- Clear your browser cookies for the affected domain and retry the request.
- Inspect the outgoing request headers in your browser's DevTools or via curl to identify the offendingly large header.
- If you control the server and the large headers are legitimate, increase the server's maximum header size configuration (e.g., `large_client_header_buffers` in Nginx, or `--max-http-header-size` in Node.js).
- Reduce the size of JWT payloads by storing data in the database and only keeping a session ID in the token.
Browser & SEO Behaviour
Browser Behavior
Browsers will display the raw error page returned by the server. Users frequently resolve this themselves by clearing their browser cookies for the site.
SEO Impact
None, unless your server somehow generates massive cookies or redirects for Googlebot, causing the bot to send large headers and get blocked. This is highly unlikely.
CDN Behavior
CDNs enforce strict header limits to protect their edge nodes. Cloudflare, for example, restricts total request headers to 32KB and will return a 431 or 400 if exceeded.
Code Examples
GET /dashboard HTTP/1.1
Host: api.example.com
Cookie: session=ey...[10,000 bytes of data]...
Authorization: Bearer ey...[Another 10,000 bytes]...// Node.js handles this automatically at the HTTP server level.
// By default, Node.js limits headers to 16KB (previously 8KB).
// You can change this limit when starting the node process:
// node --max-http-header-size=32768 server.js
// If you wanted to manually check a specific header size in Express:
app.use((req, res, next) => {
if (req.headers.authorization && req.headers.authorization.length > 8192) {
return res.status(431).send("Authorization header too large");
}
next();
});# Uvicorn (FastAPI's default server) handles header limits automatically via h11.
# You can increase the limit using the --limit-max-field-size flag.
# uvicorn main:app --limit-max-field-size 16384
@app.get("/")
def read_root(request: Request):
# This code only runs if the server hasn't already rejected it with 431
return {"message": "Headers were an acceptable size"}// In Go, the max header size is controlled by the Server struct.
// If exceeded, Go's HTTP server automatically returns 431.
server := &http.Server{
Addr: ":8080",
Handler: myHandler,
MaxHeaderBytes: 1 << 20, // 1 MB (Default is 1MB)
}
server.ListenAndServe()// Kestrel handles header limits automatically.
// You can configure it in Program.cs:
builder.WebHost.ConfigureKestrel(options => {
options.Limits.MaxRequestHeadersTotalSize = 32768; // default is 32KB
options.Limits.MaxRequestHeaderCount = 100;
});curl -v http://localhost:8080/ \
-H "X-Massive-Header: $(head -c 20000 < /dev/zero | tr '\0' 'A')"Raw HTTP Response Example
HTTP/1.1 431 Request Header Fields Too Large
Content-Type: text/html
Content-Length: 184
Connection: close
<html>
<body>
<h1>431 Request Header Fields Too Large</h1>
<p>The server refused this request because the request header fields are too large.</p>
</body>
</html>Real-world Examples
Frequently Asked Questions
How do I fix a 431 Request Header Fields Too Large error?
As an end-user, clearing your browser cookies for the specific website usually fixes it. As a developer, investigate what is bloating the headers (usually cookies or JWT tokens) and reduce their size.
Can I just increase the header size limit on my server?
Yes, most servers (Node.js, Nginx, Apache) allow you to increase the limit. However, this should be a temporary fix. You should address the root cause of the bloated headers to maintain security and performance.
Is 431 the same as 414 URI Too Long?
No. 414 applies when the URL itself is too long. 431 applies when the HTTP headers (like Cookie, Authorization, User-Agent) are too large. They are governed by different server limits.
What is a normal limit for HTTP headers?
Common defaults range from 8KB to 32KB total for all headers. Single headers are often capped at 4KB or 8KB.
Does the body payload count towards the 431 limit?
No. The 431 error strictly applies to the HTTP headers. If the request body (payload) is too large, the server will return a 413 Payload Too Large instead.
Did You Know?
The 431 status code was formalized in RFC 6585 alongside 428 and 429. Prior to 2012, servers usually just returned a generic 400 Bad Request for this scenario.
A single massive cookie is the culprit for a 431 error in over 90% of real-world web browsing cases.
Node.js CVE-2018-12121 was a denial-of-service vulnerability related to header processing, which directly led to stricter default header limits in the Node ecosystem.
Developer Tips
- Never store large data structures (like user profiles or shopping cart contents) in JWT tokens or cookies. Store a session ID and look up the data in the database.
- If using a proxy chain, be aware that each proxy might append `X-Forwarded-For` or trace ID headers, gradually inflating the header size until the final backend rejects it with a 431.
- When debugging a 431, remember that you cannot see the server's response in your application code if the web framework rejected the request before routing it to your handler.
Interview Questions
These are questions you might face in a backend or API design interview that touch on HTTP 431.
What causes a 431 Request Header Fields Too Large error?
It occurs when the combined size of the HTTP headers sent by the client, or a single massive header (typically the Cookie or Authorization header), exceeds the maximum limit configured on the web server.
If a user reports a 431 error on your website, what is the fastest immediate fix you can suggest to them?
Tell them to clear their browser cookies for the website, as cookie bloat is the most common cause of this error.
How does 431 differ from 413 Payload Too Large?
431 is triggered when the HTTP headers are too large. 413 is triggered when the HTTP request body (the data payload being uploaded or sent via POST) is too large.
Common Interview Mistakes
- Confusing 431 with 413 (Payload Too Large) or 414 (URI Too Long).
- Suggesting that increasing the server limit is the permanent solution, rather than fixing the underlying token/cookie bloat.
- Assuming the application code always has the opportunity to catch and handle this error (it is usually blocked by the web server layer before hitting the app).