Fixing HTTP 431.

What HTTP 431 means

HTTP 431 — “Request Header Fields Too Large” — is defined in RFC 6585, Section 5. The server is refusing to process the request because the header block is too large: either one field exceeds the limit, or all the headers together do. The request is rejected at the protocol level, before your application code ever runs, so there’s no application log entry and often no response body — just a bare error page.

The two usual culprits are a very long URL/query string and accumulated cookies. This guide focuses on the first, because it’s the one URL encoding causes — and the one that’s easy to fix at the source.

The detail most guides get wrong: Nginx doesn’t return 431

431 was standardized in 2012 (RFC 6585). Nginx predates it and never adopted the code, so an oversized request on Nginx surfaces differently:

• An over-long request line (the URL itself) returns 414 Request-URI Too Large.
• An over-long header field (a cookie, an auth token) returns 400 Bad Request, usually shown as “Request Header Or Cookie Too Large.”

So if you’re chasing a 431 and your stack has Nginx in front, the symptom you’ll actually see is a 400 or 414 from Nginx — same root cause, different status code. Node.js (behind or without Nginx) is where the literal 431 comes from.

How URL encoding inflates a request into a 431

The encoding-specific cause is a double-encoding loop. A faceted filter or dashboard that captures the current, already-encoded query string and re-encodes the whole thing on each click turns every % into %25 on each pass:

color%3Ablue        → first click
color%253Ablue      → second click  (%3A became %253A)
color%2525253Ablue  → a few clicks later

Each pass roughly doubles the encoded length of every special character. Within a handful of interactions the URL crosses the server’s header-size limit and the request is refused. (If you’ve got a runaway value now, paste it into our decoder with “Decode recursively” to peel every layer off and see the original.)

The fix is to never encode a string that’s already in the URL. Keep filter state as plain values in memory and rebuild the query string from scratch each time:

// Wrong — re-encodes the already-encoded URL each time
url = encodeURIComponent(location.search + newFilter);

// Right — build fresh from unencoded state, encode once
const params = new URLSearchParams();
for (const [key, value] of Object.entries(state)) {
  params.set(key, value);        // URLSearchParams encodes exactly once
}
history.replaceState(null, '', '?' + params.toString());

Server settings: the exact fixes

Fix the encoding loop first — raising a limit to accommodate a value that grows without bound only postpones the failure. Once the source is clean, if legitimate requests are still too large, adjust the server limit.

Node.js

Node’s default maximum header size is 16 KB. Raise it with the CLI flag or the server option:

# Check the current limit
node -e "console.log(require('http').maxHeaderSize)"

# Start with a larger limit
node --max-http-header-size=32768 app.js

Or set it when creating the server:

const http = require('http');
const server = http.createServer({ maxHeaderSize: 32768 }, handler);

Nginx

Nginx controls header buffers with large_client_header_buffers (default 4 8k — four 8 KB buffers) and the initial client_header_buffer_size (default 1k). Raise them in the http or server block:

http {
    client_header_buffer_size 4k;
    large_client_header_buffers 4 16k;
}

A request line cannot exceed the size of a single buffer, so the buffer size (the second number) is what caps a long URL, not the count.

Apache

Apache caps each header field with LimitRequestFieldSize (default 8,190 bytes) and the field count with LimitRequestFields (default 100):

LimitRequestFieldSize 16384
LimitRequestFields 100

A security note on raising limits

Bigger header buffers mean more memory allocated per connection, and above roughly 32 KB you start trading a functional problem for a denial-of-service one — an attacker can force large allocations across many connections. Raise limits only as far as real traffic needs, and pair the change with fixing whatever inflated the request in the first place. For a URL-encoding loop, that fix is in your code, not your server config.

Sources & standards

• RFC 6585 — Additional HTTP Status Codes. Section 5 defines 431 (Request Header Fields Too Large). rfc-editor.org/rfc/rfc6585 §5
• RFC 3986 — URI Generic Syntax. Section 2.1 defines the percent-encoding whose double-application causes the query-string inflation described here. rfc-editor.org/rfc/rfc3986 §2.1
• Nginx documentation — ngx_http_core_module. The large_client_header_buffers and client_header_buffer_size directives and their defaults. nginx.org/en/docs
• Node.js documentation. The --max-http-header-size flag and maxHeaderSize option. nodejs.org/api

Honest scope: default limits and status-code behaviour change between server versions — the values here reflect current defaults (Node 12+ at 16 KB, Nginx 4 8k, Apache 8,190 bytes). Check your own server’s version before relying on a specific number.