{"record":{"id":"510e8221404e72c7","repo":"headroomlabs-ai/headroom","slug":"ccr-sqlite-backend-init-failed-0","errorCode":null,"errorMessage":"ccr sqlite backend init failed: {0}","messagePattern":"ccr sqlite backend init failed: (.+?)","errorType":"exception","errorClass":"CcrBackendInitError","httpStatus":null,"severity":"error","filePath":"crates/headroom-core/src/ccr/backends/mod.rs","lineNumber":68,"sourceCode":"        }\n    }\n\n    /// In-memory with library defaults. Useful in tests.\n    pub fn in_memory_default() -> Self {\n        Self::InMemory {\n            capacity: crate::ccr::DEFAULT_CAPACITY,\n            ttl_seconds: crate::ccr::DEFAULT_TTL.as_secs(),\n        }\n    }\n}\n\n/// Reasons `from_config` may fail. Each variant is loud and recoverable\n/// at the proxy startup boundary — the operator is told exactly what\n/// went wrong rather than silently degrading to in-memory.\n#[derive(Debug, Error)]\npub enum CcrBackendInitError {\n    /// SQLite open / schema-create failed.\n    #[error(\"ccr sqlite backend init failed: {0}\")]\n    Sqlite(#[from] rusqlite::Error),\n    /// Redis open / PING failed (the smoke-test in `RedisCcrStore::open`).\n    #[cfg(feature = \"redis\")]\n    #[error(\"ccr redis backend init failed: {0}\")]\n    Redis(::redis::RedisError),\n    /// Operator selected a backend whose feature flag was not compiled\n    /// in. Loud failure rather than silent fallback.\n    #[error(\n        \"ccr backend `{backend}` is not compiled in; rebuild with `--features {feature}` \\\n         or pick a different backend\"\n    )]\n    UnsupportedBackend {\n        backend: &'static str,\n        feature: &'static str,\n    },\n}\n\n#[cfg(feature = \"redis\")]","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/crates/headroom-core/src/ccr/backends/mod.rs#L50-L86","documentation":"The proxy received a request whose Content-Encoding header is 'zstd' or 'zstandard', but the optional 'zstandard' package is not installed in the environment. headroom lazily imports zstandard only when a zstd-compressed body actually arrives (helpers.py:2406), so the server starts fine and fails only on such requests. The ValueError is raised from the body-reading helper so callers can translate it into a clean 400 response.","triggerScenarios":"A client sends POST /v1/messages (or any proxied route that reads the JSON body) with 'Content-Encoding: zstd' while 'zstandard' is absent from the Python environment. This happens when requests are made via HTTP libraries that transparently compress bodies (e.g. curl --compressed, some SDKs) or hand-rolled zstd-compressed JSON.","commonSituations":"Deploying headroom in a slim Docker image or minimal venv without the optional compression extras; a new client SDK version that starts using zstd by default; CI environments where only core requirements are installed.","solutions":["pip install zstandard (or add it to the deployment requirements/extra)","Configure the client to stop sending Content-Encoding: zstd and send identity/gzip instead","Catch the ValueError in your caller and return a 400 so the client learns the encoding is unsupported"],"exampleFix":"# before: client sends zstd\nrequests.post(url, data=zstandard.compress(payload), headers={\"Content-Encoding\": \"zstd\"})\n\n# after: send identity (uncompressed)\nrequests.post(url, data=payload, headers={\"Content-Encoding\": \"identity\"})","handlingStrategy":"validation","validationCode":"# Before sending: only advertise zstd when the server can decode it\nimport sys\nif \"zstandard\" not in sys.modules:\n    try:\n        import zstandard  # noqa: F401\n    except ImportError:\n        headers.pop(\"Content-Encoding\", None)  # fall back to identity","typeGuard":null,"tryCatchPattern":"try:\n    body = await _read_request_body_bytes(request)\nexcept ValueError as exc:\n    return JSONResponse({\"error\": {\"type\": \"invalid_request_error\", \"message\": str(exc)}}, status_code=400)","preventionTips":["Install zstandard in every environment that receives compressed clients","Add a startup check that imports each codec you expect clients to use","Document supported Content-Encoding values in your client wrapper"],"tags":["compression","zstd","dependency","request-body"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}