{"record":{"id":"bd3e378aa95765a5","repo":"eclipse-vertx/vert.x","slug":"431-request-header-fields-too-large-rfc6585","errorCode":null,"errorMessage":"431 Request Header Fields Too Large (RFC6585)","messagePattern":"431 Request Header Fields Too Large \\(RFC6585\\)","errorType":"http","errorClass":null,"httpStatus":431,"severity":"error","filePath":"vertx-core/src/main/java/io/vertx/core/http/HttpResponseExpectation.java","lineNumber":280,"sourceCode":"  /**\n   * 426 Upgrade Required (RFC2817)\n   */\n  HttpResponseExpectation SC_UPGRADE_REQUIRED = status(426);\n\n  /**\n   * 428 Precondition Required (RFC6585)\n   */\n  HttpResponseExpectation SC_PRECONDITION_REQUIRED = status(428);\n\n  /**\n   * 429 Too Many Requests (RFC6585)\n   */\n  HttpResponseExpectation SC_TOO_MANY_REQUESTS = status(429);\n\n  /**\n   * 431 Request Header Fields Too Large (RFC6585)\n   */\n  HttpResponseExpectation SC_REQUEST_HEADER_FIELDS_TOO_LARGE = status(431);\n\n  /**\n   * Any 5XX server error\n   */\n  HttpResponseExpectation SC_SERVER_ERRORS = status(500, 600);\n\n  /**\n   * 500 Internal Server Error\n   */\n  HttpResponseExpectation SC_INTERNAL_SERVER_ERROR = status(500);\n\n  /**\n   * 501 Not Implemented\n   */\n  HttpResponseExpectation SC_NOT_IMPLEMENTED = status(501);\n\n  /**\n   * 502 Bad Gateway","sourceCodeStart":262,"sourceCodeEnd":298,"githubUrl":"https://github.com/eclipse-vertx/vert.x/blob/fb308bd8c3f12c79f4ae89bef67fadf6c80d036e/vertx-core/src/main/java/io/vertx/core/http/HttpResponseExpectation.java#L262-L298","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Trim request headers: remove stale cookies, split oversized cookies, and drop unnecessary custom headers.","Move large state out of headers/cookies into server-side sessions or request body.","Keep tokens small (minimize JWT claims) or use token exchange/reference tokens.","If you control the server, raise the max header size (e.g. Vert.x HttpServerOptions maxHeaderSize) — but prefer shrinking headers."],"exampleFix":"// before\nrequest.putHeader(\"Cookie\", hugeAccumulatedCookieString); // > server limit -> 431\n// after\nrequest.putHeader(\"Cookie\", keepOnly(relevantCookies));\n// or increase server limit\nnew HttpServerOptions().setMaxHeaderSize(32768);","handlingStrategy":"validation","validationCode":"int headerBytes = headers.entries().stream().mapToInt(e -> e.getKey().length() + e.getValue().length()).sum();\nif (headerBytes > 8192) throw new IllegalStateException(\"request headers too large: \" + headerBytes);","typeGuard":"boolean is431(HttpClientResponse resp) { return resp.statusCode() == 431; }","tryCatchPattern":"send().onFailure(err -> {\n  if (isCauseStatus(err, 431)) trimHeadersAndRetry();\n});","preventionTips":["Keep cookies small; split or expire accumulated cookie data","Minimize JWT claims in Authorization headers","Remove debug/trace headers in production","Know the server's max header size limit"],"tags":["http","headers","cookies","vertx-http-client"],"backgroundTag":"http-error-status","analyzedSha":"fb308bd8c3f12c79f4ae89bef67fadf6c80d036e","analyzedAt":"2026-09-06T11:37:12.241Z","contentChangedAt":"2026-09-06T11:37:12.241Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}