headroomlabs-ai/headroom · error · CcrBackendInitError

ccr backend `{backend}` is not compiled in; rebuild with `--

Error message

ccr backend `{backend}` is not compiled in; rebuild with `--features {feature}` or pick a different backend

What it means

The request declared 'Content-Encoding: gzip' but gzip.decompress() raised — the body is not valid gzip data (helpers.py:2418). Typical underlying errors are gzip.BadGzipFile ('Not a gzipped file') or EOFError from a truncated stream.

Source

Thrown at crates/headroom-core/src/ccr/backends/mod.rs:76

        }
    }
}

/// Reasons `from_config` may fail. Each variant is loud and recoverable
/// at the proxy startup boundary — the operator is told exactly what
/// went wrong rather than silently degrading to in-memory.
#[derive(Debug, Error)]
pub enum CcrBackendInitError {
    /// SQLite open / schema-create failed.
    #[error("ccr sqlite backend init failed: {0}")]
    Sqlite(#[from] rusqlite::Error),
    /// Redis open / PING failed (the smoke-test in `RedisCcrStore::open`).
    #[cfg(feature = "redis")]
    #[error("ccr redis backend init failed: {0}")]
    Redis(::redis::RedisError),
    /// Operator selected a backend whose feature flag was not compiled
    /// in. Loud failure rather than silent fallback.
    #[error(
        "ccr backend `{backend}` is not compiled in; rebuild with `--features {feature}` \
         or pick a different backend"
    )]
    UnsupportedBackend {
        backend: &'static str,
        feature: &'static str,
    },
}

#[cfg(feature = "redis")]
impl From<::redis::RedisError> for CcrBackendInitError {
    fn from(err: ::redis::RedisError) -> Self {
        Self::Redis(err)
    }
}

/// Construct a CCR backend from `config`. Errors surface — never falls
/// back silently. A successful return guarantees the backend has

View on GitHub (pinned to 322425c43b)

Solutions

Verify the raw body with: python -c "import gzip; gzip.decompress(open('body.bin','rb').read())"
Make the client actually gzip the payload (e.g. requests with a prepared request whose body is gzip.compress(data)) whenever it sets the gzip header
Strip or correct Content-Encoding on any gateway that rewrites request bodies before headroom

Example fix

# before
headers = {"Content-Encoding": "gzip"}
requests.post(url, data=json.dumps(payload).encode(), headers=headers)

# after
headers = {"Content-Encoding": "gzip"}
requests.post(url, data=gzip.compress(json.dumps(payload).encode()), headers=headers)

Defensive patterns

Strategy: try-catch

Validate before calling

import gzip
try:
    gzip.decompress(compressed_body)
except Exception:
    raise RuntimeError("payload is not valid gzip — refusing to send")

Try / catch

try:
    body = await _read_request_body_bytes(request)
except ValueError as exc:
    return JSONResponse({"error": {"message": str(exc)}}, status_code=400)

Prevention

Set the header from the same code that performs the compression
Use requests-toolbelt or a session hook so encoding and header stay in sync
Integration-test the compressed path, not just plain bodies

When it happens

Trigger: Sending a plain or deflate-compressed body with a 'Content-Encoding: gzip' header; chunked upload interrupted mid-body so the gzip trailer is missing; a front proxy stripped the gzip encoding but kept the header.

Common situations: Mismatches between encoding label and actual bytes; retry middleware that re-reads a consumed/short body stream; test harnesses that hand-craft bodies with copy-pasted headers.

Related errors

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