{"record":{"id":"e21678189cfd9193","repo":"headroomlabs-ai/headroom","slug":"mode-must-be-token-or-cache","errorCode":null,"errorMessage":"mode must be 'token' or 'cache'","messagePattern":"mode must be 'token' or 'cache'","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"headroom/testing/harness.py","lineNumber":551,"sourceCode":"    def kompress_enabled(self, value: bool) -> None:\n        self.proxy.disable_kompress = not bool(value)\n\n    @property\n    def optimize(self) -> bool:\n        return cast(bool, self.proxy.optimize)\n\n    @optimize.setter\n    def optimize(self, value: bool) -> None:\n        self.proxy.optimize = bool(value)\n\n    @property\n    def mode(self) -> str:\n        return cast(str, self.proxy.mode)\n\n    @mode.setter\n    def mode(self, value: Literal[\"token\", \"cache\"]) -> None:\n        if value not in {\"token\", \"cache\"}:\n            raise ValueError(\"mode must be 'token' or 'cache'\")\n        self.proxy.mode = value\n\n    @property\n    def default_mode(self) -> HeadroomMode:\n        return self.headroom.default_mode\n\n    @default_mode.setter\n    def default_mode(self, value: str | HeadroomMode) -> None:\n        self.headroom.default_mode = _coerce_headroom_mode(value)\n\n    def __setattr__(self, name: str, value: Any) -> None:\n        if name in {\"headroom\", \"proxy\"}:\n            raise AttributeError(f\"{name} is read-only; mutate its fields instead\")\n        descriptor = getattr(type(self), name, None)\n        if isinstance(descriptor, property) and descriptor.fset is not None:\n            descriptor.fset(self, value)\n            return\n        if hasattr(self.proxy, name):","sourceCodeStart":533,"sourceCodeEnd":569,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/testing/harness.py#L533-L569","documentation":"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.","triggerScenarios":"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.","commonSituations":"User-supplied mode strings from CLI flags; configs ported from another tool whose modes are named differently; case differences after copy-paste.","solutions":["Use exactly 'token' or 'cache' (lowercase).","Normalize incoming strings: value.strip().lower() and map synonyms before assigning.","If the value is user-driven, validate against {'token','cache'} at the input boundary."],"exampleFix":"# before\nharness.config.mode = 'Token'  # ValueError\n\n# after\nharness.config.mode = 'token'","handlingStrategy":"validation","validationCode":"MODES = {'token', 'cache'}\n\ndef safe_mode(v: str) -> str:\n    v = str(v).strip().lower()\n    if v not in MODES:\n        raise ValueError(f'mode must be one of {sorted(MODES)}, got {v!r}')\n    return v","typeGuard":"def is_harness_mode(v: str) -> bool:\n    return isinstance(v, str) and v in {'token', 'cache'}","tryCatchPattern":null,"preventionTips":["Offer mode as a closed choice (CLI choices=, UI dropdown).","Lowercase+strip any externally sourced mode string before assignment."],"tags":["testing","harness","validation","enum"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}