headroomlabs-ai/headroom · error · ParseError::PreludeCrcMismatch

bedrock_eventstream_crc_mismatch

bedrock_eventstream_crc_mismatch

Error message

prelude CRC mismatch: expected={expected:#010x} got={got:#010x}

What it means

The HEADROOM_MEMORY_INJECTION_MODE environment variable is set to something other than 'live_zone_tail' or 'disabled' (memory_injection_mode_policy.py:19). Values are trimmed/lowercased, so 'Live_Zone_Tail' is fine, but 'on', 'off', 'true', 'none', or typos fail fast at config resolution.

Source

Thrown at crates/headroom-proxy/src/bedrock/eventstream.rs:164

    /// requires (12-byte prelude, headers block, 4-byte trailing CRC).
    /// Wire-format violation; AWS would never emit this. Surfaced
    /// loudly so the handler can 5xx and log it.
    #[error(
        "implausible prelude lengths: total_length={total_length}, headers_length={headers_length}"
    )]
    ImplausiblePreludeLengths {
        total_length: u32,
        headers_length: u32,
    },
    /// `total_length` exceeds the configured `max_message_bytes` cap.
    /// The cap defaults to 32 MiB; configurable via
    /// [`EventStreamParser::with_max_message_bytes`].
    #[error("message too large: total_length={total_length} cap={cap}")]
    MessageTooLarge { total_length: u32, cap: usize },
    /// CRC32 of the first 8 bytes of the prelude did not match the
    /// 9th-12th bytes. Indicates corruption (in-flight bit-flip,
    /// truncated chunk, or — if persistent — wire-format version skew).
    #[error("prelude CRC mismatch: expected={expected:#010x} got={got:#010x}")]
    PreludeCrcMismatch { expected: u32, got: u32 },
    /// CRC32 of the entire message body did not match the trailing
    /// 4-byte CRC. Indicates the message bytes were corrupted in
    /// flight.
    #[error("message CRC mismatch: expected={expected:#010x} got={got:#010x}")]
    MessageCrcMismatch { expected: u32, got: u32 },
    /// A header's `name_len` extended past the declared end of the
    /// headers block.
    #[error("truncated header at offset {offset}: needs {needed} more bytes")]
    TruncatedHeader { offset: usize, needed: usize },
    /// A header's name was not valid UTF-8.
    #[error("header name not valid UTF-8 at offset {offset}: {source}")]
    HeaderNameNotUtf8 {
        offset: usize,
        #[source]
        source: std::str::Utf8Error,
    },
    /// A string-typed header value was not valid UTF-8.

View on GitHub (pinned to 322425c43b)

Solutions

1. Set the variable to 'live_zone_tail' or 'disabled', or unset it (defaults to live_zone_tail)
2. Check: echo $HEADROOM_MEMORY_INJECTION_MODE and fix the value in .env/compose/manifest
3. If you meant to turn it off, the word is 'disabled', not 'false' or 'off'

Example fix

# before
HEADROOM_MEMORY_INJECTION_MODE=false

# after
HEADROOM_MEMORY_INJECTION_MODE=disabled

raw = os.environ.get("HEADROOM_MEMORY_INJECTION_MODE")
if raw is not None and raw.strip().lower() not in ("live_zone_tail", "disabled"):
    raise SystemExit(f"bad HEADROOM_MEMORY_INJECTION_MODE={raw!r}; use live_zone_tail/disabled")

When it happens

Trigger: Exporting HEADROOM_MEMORY_INJECTION_MODE=0/1 in a start script; a k8s ConfigMap carrying boolean-style values; typo 'live-zone-tail' (hyphens instead of underscores).

Common situations: Boolean-env-var conventions colliding with enum-valued config; template normalization of all toggles to true/false; hyphen/underscore confusion copied from docs.

Related errors

• recommendations IO error at {path}: {source}
• bedrock_eventstream_parse_failed
• Proxy failed to start on port {port} within {timeout_seconds
• max_size must be at least 1, got {max_size}
• OpenAI API key required. Provide api_key parameter or set OP

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/b8d9a67dcb385bcc. Report an issue: GitHub.