headroomlabs-ai/headroom · error · RecommendationsError

recommendations IO error at {path}: {source}

Error message

recommendations IO error at {path}: {source}

What it means

The HEADROOM_STRIP_INTERNAL_HEADERS (name from STRIP_INTERNAL_HEADERS_ENV) environment variable was set to a value that is neither 'enabled', 'disabled', nor empty (internal_header_policy.py:22). Values are trimmed and lowercased before matching, so 'Enabled' works, but 'on', 'true', '1', or typos like 'diabled' raise at startup/config-resolution time.

Source

Thrown at crates/headroom-core/src/transforms/recommendations.rs:255

/// exposes the API surface.
pub fn get(
    auth_mode: AuthMode,
    model: &str,
    structure_hash: &str,
) -> Option<&'static Recommendation> {
    load_default().lookup(auth_mode, model, structure_hash)
}

/// Errors surfaced by the loader. Marked non-exhaustive so we can add
/// future variants without breaking callers.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum RecommendationsError {
    /// File doesn't exist on disk.
    #[error("recommendations file not found: {0}")]
    Missing(PathBuf),
    /// Filesystem error other than NotFound.
    #[error("recommendations IO error at {path}: {source}")]
    Io {
        path: PathBuf,
        #[source]
        source: std::io::Error,
    },
    /// TOML parse failure (typed wrapper for ergonomics).
    #[error("recommendations TOML parse error: {0}")]
    Parse(#[from] toml::de::Error),
}

#[cfg(test)]
mod tests {
    use super::*;

    fn sample_toml() -> &'static str {
        r#"
[[recommendation]]
auth_mode = "payg"

View on GitHub (pinned to 322425c43b)

Solutions

1. Set the variable to exactly 'enabled' or 'disabled', or unset it (default is enabled)
2. Search the deployment for the variable: grep -r HEADROOM_STRIP_INTERNAL_HEADERS .env docker-compose.yml k8s/
3. If you intended 'false', change it to 'disabled'

Example fix

# before
HEADROOM_STRIP_INTERNAL_HEADERS=true

# after
HEADROOM_STRIP_INTERNAL_HEADERS=enabled

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

When it happens

Trigger: Setting HEADROOM_STRIP_INTERNAL_HEADERS=true (boolean-style value) in .env or docker-compose; a typo in a k8s ConfigMap; scripts that export 0/1 flags for all toggles.

Common situations: Teams used to boolean env vars assume 0/1 works; CI configs generated from templates that normalize all flags to true/false; renames or stale docs.

Related errors

• bedrock_eventstream_crc_mismatch
• bedrock_eventstream_parse_failed
• Proxy failed to start on port {port} within {timeout_seconds
• headroom-oauth2 misconfigured: {e}
• compression engine startup failed: {0}

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