hyperium/hyper · error · hyper::Error

message head is too large

Error message

message head is too large

What it means

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().

Source

Thrown at src/error.rs:372

        // Find an h2::Reason somewhere in the cause stack, if it exists,
        // otherwise assume an INTERNAL_ERROR.
        self.find_source::<h2::Error>()
            .and_then(|h2_err| h2_err.reason())
            .unwrap_or(h2::Reason::INTERNAL_ERROR)
    }

    pub(super) fn new_canceled() -> Error {
        Error::new(Kind::Canceled)
    }

    #[cfg(all(any(feature = "client", feature = "server"), feature = "http1"))]
    pub(super) fn new_incomplete() -> Error {
        Error::new(Kind::IncompleteMessage)
    }

    #[cfg(all(any(feature = "client", feature = "server"), feature = "http1"))]
    pub(super) fn new_too_large() -> Error {
        Error::new(Kind::Parse(Parse::TooLarge))
    }

    #[cfg(all(any(feature = "client", feature = "server"), feature = "http1"))]
    pub(super) fn new_version_h2() -> Error {
        Error::new(Kind::Parse(Parse::VersionH2))
    }

    #[cfg(all(any(feature = "client", feature = "server"), feature = "http1"))]
    pub(super) fn new_unexpected_message() -> Error {
        Error::new(Kind::UnexpectedMessage)
    }

    #[cfg(all(
        any(feature = "client", feature = "server"),
        any(feature = "http1", feature = "http2")
    ))]
    pub(super) fn new_io(cause: std::io::Error) -> Error {
        Error::new(Kind::Io).with(cause)

View on GitHub (pinned to 084473f728)

Solutions

1. 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.
2. If the head is genuinely too big, trim headers/cookies at the source before sending.
3. 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.

Example fix

// before: default ~409KB head limit rejects large legitimate heads
let mut http = Http::new();

// after: raise the cap to what your workload actually needs
let mut http = Http::new();
http.max_buf_size(1024 * 1024); // 1 MiB

// Before sending, sanity-check that your head fits your configured limit.
const MAX_HEAD: usize = 1024 * 1024; // match Builder::max_buf_size
fn head_size(method: &str, uri: &str, hdrs: &[(String, String)]) -> usize {
    let line = method.len() + uri.len() + 12; // rough request-line overhead
    line + hdrs.iter().map(|(k, v)| k.len() + v.len() + 4).sum::<usize>()
}
// assert!(head_size(...) <= MAX_HEAD, "head too large");

fn is_head_too_large(err: &hyper::Error) -> bool {
    err.is_parse_too_large()
}

match parse_or_recv().await {
    Err(e) if e.is_parse_too_large() => { /* respond 431 / trim headers */ }
    other => other,
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Partial header
• chunk trailers bytes over limit
• chunk extensions over limit
• chunk trailers count overflow
• Invalid header name: {:?}

AI-assisted analysis of hyperium/hyper@084473f728 (2026-08-06). Data as JSON: /data/errors/3c3c2ee73f079f33.json. Report an issue: GitHub.