headroomlabs-ai/headroom · error · ValueError

mode must be 'token' or 'cache'

Error message

mode must be 'token' or 'cache'

What it means

ValueError raised by the mode setter on the harness config (headroom/testing/harness.py:551) when a value outside {'token', 'cache'} is assigned. mode is a Literal['token','cache'] field selecting whether the proxy optimizes token usage or cache usage; the setter validates before forwarding to self.proxy.mode, so an invalid mode never reaches the proxy.

Source

Thrown at headroom/testing/harness.py:551

    def kompress_enabled(self, value: bool) -> None:
        self.proxy.disable_kompress = not bool(value)

    @property
    def optimize(self) -> bool:
        return cast(bool, self.proxy.optimize)

    @optimize.setter
    def optimize(self, value: bool) -> None:
        self.proxy.optimize = bool(value)

    @property
    def mode(self) -> str:
        return cast(str, self.proxy.mode)

    @mode.setter
    def mode(self, value: Literal["token", "cache"]) -> None:
        if value not in {"token", "cache"}:
            raise ValueError("mode must be 'token' or 'cache'")
        self.proxy.mode = value

    @property
    def default_mode(self) -> HeadroomMode:
        return self.headroom.default_mode

    @default_mode.setter
    def default_mode(self, value: str | HeadroomMode) -> None:
        self.headroom.default_mode = _coerce_headroom_mode(value)

    def __setattr__(self, name: str, value: Any) -> None:
        if name in {"headroom", "proxy"}:
            raise AttributeError(f"{name} is read-only; mutate its fields instead")
        descriptor = getattr(type(self), name, None)
        if isinstance(descriptor, property) and descriptor.fset is not None:
            descriptor.fset(self, value)
            return
        if hasattr(self.proxy, name):

View on GitHub (pinned to 322425c43b)

Solutions

1. Use exactly 'token' or 'cache' (lowercase).
2. Normalize incoming strings: value.strip().lower() and map synonyms before assigning.
3. If the value is user-driven, validate against {'token','cache'} at the input boundary.

Example fix

# before
harness.config.mode = 'Token'  # ValueError

# after
harness.config.mode = 'token'

MODES = {'token', 'cache'}

def safe_mode(v: str) -> str:
    v = str(v).strip().lower()
    if v not in MODES:
        raise ValueError(f'mode must be one of {sorted(MODES)}, got {v!r}')
    return v

def is_harness_mode(v: str) -> bool:
    return isinstance(v, str) and v in {'token', 'cache'}

When it happens

Trigger: harness.config.mode = 'Token' (wrong case); mode = 'tokens' or 'caching' (plural); passing a UI/env string directly without normalizing; assigning None or an empty string.

Common situations: User-supplied mode strings from CLI flags; configs ported from another tool whose modes are named differently; case differences after copy-paste.

Related errors

• HeadroomSuite requires at least one scenario
• Invalid memory_mode={config.memory_mode!r}; expected one of
• Invalid memory_storage_mode={config.memory_storage_mode!r};
• unknown rollout channel {value!r}
• {token!r} not one of {list(field.choices)}

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