{"id":"3c3c2ee73f079f33","repo":"hyperium/hyper","slug":"message-head-is-too-large","errorCode":null,"errorMessage":"message head is too large","messagePattern":"message head is too large","errorType":"exception","errorClass":"hyper::Error","httpStatus":null,"severity":"error","filePath":"src/error.rs","lineNumber":372,"sourceCode":"        // Find an h2::Reason somewhere in the cause stack, if it exists,\n        // otherwise assume an INTERNAL_ERROR.\n        self.find_source::<h2::Error>()\n            .and_then(|h2_err| h2_err.reason())\n            .unwrap_or(h2::Reason::INTERNAL_ERROR)\n    }\n\n    pub(super) fn new_canceled() -> Error {\n        Error::new(Kind::Canceled)\n    }\n\n    #[cfg(all(any(feature = \"client\", feature = \"server\"), feature = \"http1\"))]\n    pub(super) fn new_incomplete() -> Error {\n        Error::new(Kind::IncompleteMessage)\n    }\n\n    #[cfg(all(any(feature = \"client\", feature = \"server\"), feature = \"http1\"))]\n    pub(super) fn new_too_large() -> Error {\n        Error::new(Kind::Parse(Parse::TooLarge))\n    }\n\n    #[cfg(all(any(feature = \"client\", feature = \"server\"), feature = \"http1\"))]\n    pub(super) fn new_version_h2() -> Error {\n        Error::new(Kind::Parse(Parse::VersionH2))\n    }\n\n    #[cfg(all(any(feature = \"client\", feature = \"server\"), feature = \"http1\"))]\n    pub(super) fn new_unexpected_message() -> Error {\n        Error::new(Kind::UnexpectedMessage)\n    }\n\n    #[cfg(all(\n        any(feature = \"client\", feature = \"server\"),\n        any(feature = \"http1\", feature = \"http2\")\n    ))]\n    pub(super) fn new_io(cause: std::io::Error) -> Error {\n        Error::new(Kind::Io).with(cause)","sourceCodeStart":354,"sourceCodeEnd":390,"githubUrl":"https://github.com/hyperium/hyper/blob/084473f728f9d07b3be5845475aa2f62ed9ff579/src/error.rs#L354-L390","documentation":"Thrown via Error::new_too_large() (src/error.rs:372, Kind::Parse(Parse::TooLarge)). It fires when an HTTP/1 message head (request line/status line plus all headers) exceeds the configured maximum buffer, or when httparse reports TooManyHeaders. The default cap is DEFAULT_MAX_BUFFER_SIZE = 8192 + 4096*100 (~409 KB) in proto/h1/io.rs:23; the count of headers defaults to 100 (role.rs:31). Detect with Error::is_parse_too_large().","triggerScenarios":"proto/h1/io.rs:202 returns new_too_large() when the parsed head buffer grows past max_buf_size; httparse::Error::TooManyHeaders maps to Parse::TooLarge (error.rs:661). Triggered by a request/response with an enormous head, a huge cookie/authorization header, or hundreds of headers.","commonSituations":"A proxy forwarding a large JWT or long cookie chain; an API gateway receiving unusually many headers from a legacy client; a misconfigured client sending the whole body as headers; a denial-of-service attempt with a giant head. Raising or lowering max_buf_size / max_headers on the Builder changes the threshold.","solutions":["If legitimate heads exceed the limit, raise it via Builder::max_buf_size (client/conn/http1.rs:520, server/conn/http1.rs:381) — but keep it bounded to avoid memory abuse.","If the head is genuinely too big, trim headers/cookies at the source before sending.","If this is a server, reject such clients with a 431 Request Header Fields Too Large and confirm the cap is intentional for your workload."],"exampleFix":"// before: default ~409KB head limit rejects large legitimate heads\nlet mut http = Http::new();\n\n// after: raise the cap to what your workload actually needs\nlet mut http = Http::new();\nhttp.max_buf_size(1024 * 1024); // 1 MiB","handlingStrategy":"validation","validationCode":"// Before sending, sanity-check that your head fits your configured limit.\nconst MAX_HEAD: usize = 1024 * 1024; // match Builder::max_buf_size\nfn head_size(method: &str, uri: &str, hdrs: &[(String, String)]) -> usize {\n    let line = method.len() + uri.len() + 12; // rough request-line overhead\n    line + hdrs.iter().map(|(k, v)| k.len() + v.len() + 4).sum::<usize>()\n}\n// assert!(head_size(...) <= MAX_HEAD, \"head too large\");","typeGuard":"fn is_head_too_large(err: &hyper::Error) -> bool {\n    err.is_parse_too_large()\n}","tryCatchPattern":"match parse_or_recv().await {\n    Err(e) if e.is_parse_too_large() => { /* respond 431 / trim headers */ }\n    other => other,\n}","preventionTips":["Set Builder::max_buf_size deliberately for your workload; don't leave it at the default if you send big heads.","Cap the number and size of cookies/authorization headers at the source.","On a server, log is_parse_too_large() at info and return 431 Request Header Fields Too Large."],"tags":["http1","parse","headers","limits","rust"],"analyzedSha":"084473f728f9d07b3be5845475aa2f62ed9ff579","analyzedAt":"2026-08-06T01:20:18.522Z","schemaVersion":2}