{"record":{"id":"6de8639ff20b3938","repo":"headroomlabs-ai/headroom","slug":"compression-engine-startup-failed-0","errorCode":null,"errorMessage":"compression engine startup failed: {0}","messagePattern":"compression engine startup failed: (.+?)","errorType":"error_code","errorClass":"ProxyError::CompressionStartup","httpStatus":null,"severity":"critical","filePath":"crates/headroom-proxy/src/error.rs","lineNumber":38,"sourceCode":"\n    #[error(\"io error: {0}\")]\n    Io(#[from] std::io::Error),\n\n    /// PR-A8 / P5-59: request body exceeded the configured cap. RFC 7231\n    /// §6.5.11: 413 Payload Too Large. Previously surfaced as\n    /// `InvalidHeader` (400) which mis-classified an oversize body as a\n    /// header parse error; clients with retry-on-413 logic broke.\n    #[error(\"request body exceeds configured limit: {0}\")]\n    PayloadTooLarge(String),\n\n    /// Surfaced when `--compression` is enabled but the proxy can't\n    /// build the IntelligentContextManager at startup (e.g. the\n    /// embedded tokenizer asset failed to initialize). Bubbles up to\n    /// `main` as a fatal startup error rather than a per-request\n    /// failure — if compression is configured but the engine won't\n    /// build, the operator should know immediately, not at first\n    /// LLM request.\n    #[error(\"compression engine startup failed: {0}\")]\n    CompressionStartup(String),\n}\n\nimpl IntoResponse for ProxyError {\n    fn into_response(self) -> Response {\n        let (status, msg) = match &self {\n            ProxyError::Upstream(e) if e.is_timeout() => (\n                StatusCode::GATEWAY_TIMEOUT,\n                format!(\"upstream timeout: {e}\"),\n            ),\n            ProxyError::Upstream(e) if e.is_connect() => (\n                StatusCode::BAD_GATEWAY,\n                format!(\"upstream connect error: {e}\"),\n            ),\n            ProxyError::Upstream(_) => (StatusCode::BAD_GATEWAY, self.to_string()),\n            ProxyError::InvalidUpstream(_) => (StatusCode::BAD_GATEWAY, self.to_string()),\n            ProxyError::InvalidHeader(_) => (StatusCode::BAD_REQUEST, self.to_string()),\n            ProxyError::PayloadTooLarge(_) => (StatusCode::PAYLOAD_TOO_LARGE, self.to_string()),","sourceCodeStart":20,"sourceCodeEnd":56,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/crates/headroom-proxy/src/error.rs#L20-L56","documentation":"The IntelligentContextManager (compression engine) failed to build at startup — canonically because the embedded tokenizer asset failed to initialize. By design this is fatal at boot via main, not a per-request error; if it ever escapes into the handler path it maps to 500 as a defensive measure.","triggerScenarios":"Starting the proxy with --compression when the embedded tokenizer asset is missing/corrupt in the build (feature flags excluded it, asset registry mismatch, truncated build artifact).","commonSituations":"Building from source without the asset-generating feature/step; a broken release artifact or docker layer; upgrading the crate where the asset format or initialization API changed but the binary mixes old asset with new code.","solutions":["Treat a startup abort with this message as 'do not run without compression': either fix the asset or drop --compression.","Rebuild from a clean target so the tokenizer asset is re-embedded by the current build script.","Verify the release artifact integrity (checksum) if using prebuilt binaries/docker images.","If embedding your own tokenizer, confirm the asset version matches the engine's expected format."],"exampleFix":null,"handlingStrategy":"validation","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat startup abort with this message as fatal-by-design; don't wrap main in a catch that continues serving.","Build from clean targets so the tokenizer asset re-embeds.","Verify release artifact checksums before deploying with --compression."],"tags":["startup","compression","assets","config","rust"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}