headroomlabs-ai/headroom · error · ValueError

Invalid {STRIP_INTERNAL_HEADERS_ENV}={normalized!r}; expecte

Error message

Invalid {STRIP_INTERNAL_HEADERS_ENV}={normalized!r}; expected 'enabled' or 'disabled'

What it means

Error "Invalid {STRIP_INTERNAL_HEADERS_ENV}={normalized!r}; expected 'enabled' or 'disabled'" thrown in headroomlabs-ai/headroom.

Source

Thrown at headroom/proxy/internal_header_policy.py:22

from collections.abc import Mapping
from typing import Literal, cast

INTERNAL_HEADER_PREFIX = "x-headroom-"
STRIP_INTERNAL_HEADERS_ENV = "HEADROOM_STRIP_INTERNAL_HEADERS"
StripInternalHeadersMode = Literal["enabled", "disabled"]
STRIP_INTERNAL_HEADERS_DEFAULT: StripInternalHeadersMode = "enabled"


def resolve_strip_internal_headers_mode(raw: str | None) -> StripInternalHeadersMode:
    """Resolve the configured internal-header strip mode."""

    normalized = (raw or "").strip().lower()
    if not normalized:
        return STRIP_INTERNAL_HEADERS_DEFAULT
    if normalized in ("enabled", "disabled"):
        return cast(StripInternalHeadersMode, normalized)
    raise ValueError(
        f"Invalid {STRIP_INTERNAL_HEADERS_ENV}={normalized!r}; expected 'enabled' or 'disabled'"
    )


def strip_internal_headers(
    headers: Mapping[str, str],
    *,
    mode: StripInternalHeadersMode,
) -> dict[str, str]:
    """Return a copy of headers with internal x-headroom-* request headers removed."""

    if mode == "disabled":
        return dict(headers)
    return {
        key: value
        for key, value in headers.items()
        if not key.lower().startswith(INTERNAL_HEADER_PREFIX)
    }

View on GitHub (pinned to 322425c43b)

Solutions

1. Set {STRIP_INTERNAL_HEADERS_ENV} to 'enabled' or 'disabled' (case-insensitive)
2. Unset the variable to use the default policy

When it happens

Trigger: Raised at startup when the internal-header stripping policy environment variable holds a value other than 'enabled' or 'disabled'.

Common situations: See trigger scenarios.

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