eclipse-vertx/vert.x · error

431 Request Header Fields Too Large (RFC6585)

Error message

431 Request Header Fields Too Large (RFC6585)

What it means

SC_REQUEST_HEADER_FIELDS_TOO_LARGE is an HttpResponseExpectation constant for HTTP 431 (RFC6585). The server refuses the request because its header fields (or an individual header) are too large — commonly oversized cookies, tokens, or too many headers. Vert.x exposes it for status assertions in HttpClient expectations.

Source

Thrown at vertx-core/src/main/java/io/vertx/core/http/HttpResponseExpectation.java:280

  /**
   * 426 Upgrade Required (RFC2817)
   */
  HttpResponseExpectation SC_UPGRADE_REQUIRED = status(426);

  /**
   * 428 Precondition Required (RFC6585)
   */
  HttpResponseExpectation SC_PRECONDITION_REQUIRED = status(428);

  /**
   * 429 Too Many Requests (RFC6585)
   */
  HttpResponseExpectation SC_TOO_MANY_REQUESTS = status(429);

  /**
   * 431 Request Header Fields Too Large (RFC6585)
   */
  HttpResponseExpectation SC_REQUEST_HEADER_FIELDS_TOO_LARGE = status(431);

  /**
   * Any 5XX server error
   */
  HttpResponseExpectation SC_SERVER_ERRORS = status(500, 600);

  /**
   * 500 Internal Server Error
   */
  HttpResponseExpectation SC_INTERNAL_SERVER_ERROR = status(500);

  /**
   * 501 Not Implemented
   */
  HttpResponseExpectation SC_NOT_IMPLEMENTED = status(501);

  /**
   * 502 Bad Gateway

View on GitHub (pinned to fb308bd8c3)

Solutions

1. Trim request headers: remove stale cookies, split oversized cookies, and drop unnecessary custom headers.
2. Move large state out of headers/cookies into server-side sessions or request body.
3. Keep tokens small (minimize JWT claims) or use token exchange/reference tokens.
4. If you control the server, raise the max header size (e.g. Vert.x HttpServerOptions maxHeaderSize) — but prefer shrinking headers.

Example fix

// before
request.putHeader("Cookie", hugeAccumulatedCookieString); // > server limit -> 431
// after
request.putHeader("Cookie", keepOnly(relevantCookies));
// or increase server limit
new HttpServerOptions().setMaxHeaderSize(32768);

int headerBytes = headers.entries().stream().mapToInt(e -> e.getKey().length() + e.getValue().length()).sum();
if (headerBytes > 8192) throw new IllegalStateException("request headers too large: " + headerBytes);

boolean is431(HttpClientResponse resp) { return resp.statusCode() == 431; }

send().onFailure(err -> {
  if (isCauseStatus(err, 431)) trimHeadersAndRetry();
});

When it happens

Trigger: Sending requests with very large Cookie headers (accumulated session data), huge Authorization/JWT tokens, or many custom headers, against servers with strict max-header-size limits (e.g. Vert.x/Tomcat/Nginx header limits). Appears when expecting success but the server replies 431.

Common situations: Cookie bloat from storing session state client-side; JWTs embedding many claims/permissions; debug/trace headers left enabled; server-side max-header-size lowered in a security hardening change.

Related errors

• a header value contains a prohibited character '127': <value
• a header value must not end with '\r' or '\n':<seq>
• a header value contains a prohibited character '127': <seq>
• only '\n' is allowed after '\r': <seq>
• only ' ' and '\t' are allowed after '\n': <seq>

AI-assisted analysis of eclipse-vertx/vert.x@fb308bd8c3 (2026-09-06). Data as JSON: /api/errors/bd3e378aa95765a5. Report an issue: GitHub.