431 Request Header Fields Too Large: causes and fixes
Meaning
431 means the server refused your request because its headers are too big, in total or in one field such as Cookie. Trim them before resending.
The request line and headers you sent were bigger than the server was willing to read, so it refused the request before looking at the URL. RFC 6585 section 5 defines “431 Request Header Fields Too Large” for a server “unwilling to process the request because its header fields are too large”. The code covers a large total and a single oversized field, and in the second case the response SHOULD say which field it was. The RFC also says the request MAY be resubmitted after the headers are reduced. Sending the same headers again gets the same answer.
Cookie is the usual culprit. A long-running session collects cookies from every response, and the whole cookie jar for the host goes out on every request. Large bearer tokens and long Referer values come next.
The ceiling is different on every server
We grew a single Cookie header against five servers with default settings, using raw sockets so every byte was counted, and bisected to the exact size where 200 turned into a refusal. Both full runs gave identical byte counts. “Largest request accepted” counts the request line, every header line and the closing blank line.
| Server (defaults) | Largest request accepted | First refusal |
|---|---|---|
| Apache httpd 2.4.67 | 8,253 bytes | 400 Bad Request |
| Node.js 24.2.0 | 16,412 bytes | 431 Request Header Fields Too Large |
| Squid 6.13, as a forward proxy | 65,535 bytes | 431 Request Header Fields Too Large |
| Python 3.15.0 http.server | 65,596 bytes | 431 Line too long |
| Go 1.24.4 net/http | 1,052,672 bytes | 431 Request Header Fields Too Large |
Three details matter more than the numbers. Apache does not send 431 at all: it answers 400 with “Size of a request header field exceeds server limit”, and nginx does the same through its internal 494 code, whose page is titled “400 Request Header Or Cookie Too Large”. A client that only checks for 431 misses both. Python puts its own message in the status line, so the reason phrase reads “Line too long”, and a 101st header line produces “431 Too many headers” regardless of size. Go’s ceiling sat exactly 4,096 bytes above its DefaultMaxHeaderBytes of 1,048,576.
Reproduce it with curl
An unmodified Node.js server is enough, since its documented default is 16 KiB:
// node431.mjs, Node.js 24.2.0, no options changed
import http from 'node:http';
http.createServer((req, res) => res.end('ok\n')).listen(37431, '127.0.0.1');
A 20,000-character cookie pushes curl 8.23.0 over it. The long Cookie line is left out of the paste:
$ python3 -c "print('Cookie: a='+'x'*20000)" > cookie20k.txt
$ curl -sv -H @cookie20k.txt http://127.0.0.1:37431/
* Trying 127.0.0.1:37431...
* Established connection to 127.0.0.1 (127.0.0.1 port 37431) from 127.0.0.1 port 57081
* using HTTP/1.x
> GET / HTTP/1.1
> Host: 127.0.0.1:37431
> User-Agent: curl/8.23.0
> Accept: */*
>
* Request completely sent off
< HTTP/1.1 431 Request Header Fields Too Large
< Connection: close
<
{ [0 bytes data]
* shutting down connection #0
Node’s 431 has no body, so it does not say which header was too big. To find the fat one yourself, measure what your client is about to send. This uses Python 3.9.6 with requests 2.32.3 against the same server:
import requests
URL = "http://127.0.0.1:37431/"
s = requests.Session()
for i in range(40): # a session that picked up 40 tracking cookies
s.cookies.set(f"_trk{i}", "v" * 400, domain="127.0.0.1", path="/")
def header_sizes(session, url):
req = session.prepare_request(requests.Request("GET", url))
return {k: len(k) + 2 + len(v) + 2 for k, v in req.headers.items()} # "Name: value\r\n"
sizes = header_sizes(s, URL)
for name, n in sorted(sizes.items(), key=lambda kv: -kv[1]):
print(f"{n:>6} {name}")
print("status:", s.get(URL).status_code)
for c in [c for c in s.cookies if c.name.startswith("_trk")]:
s.cookies.clear(c.domain, c.path, c.name) # drop what the target does not need
print("after trim:", sum(header_sizes(s, URL).values()), "bytes, status:", s.get(URL).status_code)
16358 Cookie
42 Accept-Encoding
36 User-Agent
24 Connection
13 Accept
status: 431
after trim: 115 bytes, status: 200
The prepared request does not include Host yet, which is added at send time. For what other clients put in their headers by default, see What HTTP clients send before you configure anything.
When a proxy returns 431
Look at who signed the response. Squid 6.13 refusing a request itself, at its documented 64 KB request_header_max_size, sent Server: squid/6.13 and X-Squid-Error: ERR_TOO_BIG 0. When Squid forwarded a 20 KB cookie to the Node server and relayed Node’s refusal, the 431 had no Server header from Squid and gained Via: 1.1 proxy-host (squid/6.13) (hostname masked).
Proxies also make requests bigger on the way through. A curl request that reached our capture server as 79 bytes direct arrived as 206 bytes through Squid with default settings, which added Via, X-Forwarded-For, Cache-Control and Connection. The exact growth depends on the proxy’s hostname in Via. One hop rarely matters on its own, but a request already close to a total limit, such as Node’s 16 KiB, can cross it after a chain of them.
For scrapers, the fix is usually cookie hygiene. If you rotate the exit IP, rotate the cookie jar with it, as Rotating vs sticky sessions explains; replaying one growing jar from many addresses also looks odd to the target.
Causes and fixes
| Cause | How to confirm it | What to change |
|---|---|---|
| Cookie jar grew during a long session | Cookie is the largest header in the size dump, and grows over time | Clear the jar when you change identity; drop cookies the target does not need |
Cookies from other apps on localhost |
Fails only in local development; works in a private window | Clear localhost cookies, or start Node with --max-http-header-size=32768 |
| Oversized Authorization or custom header | That header tops the size dump | Send a shorter token, or move data into the body where the API allows |
| Headers added along a proxy chain | Compare the request size at the origin direct and through the proxy | Fewer hops; on a Squid you run, via off and forwarded_for delete |
| A strict server limit | 400 rather than 431 at around 8 KB in a single field | On your own server, raise LimitRequestFieldSize or large_client_header_buffers |
The localhost case catches developers because cookies ignore ports. RFC 6265 states it plainly: “Cookies do not provide isolation by port.” Every app you have run on localhost adds to the same jar.