{"record":{"id":"6d7500381f407d74","repo":"headroomlabs-ai/headroom","slug":"unhandled-authmode-variant-mode-r","errorCode":null,"errorMessage":"Unhandled AuthMode variant: {mode!r}","messagePattern":"Unhandled AuthMode variant: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"headroom/transforms/compression_policy.py","lineNumber":239,"sourceCode":"        # ``tests/test_compression_policy.py`` is the canary that\n        # catches a future divergence and forces a deliberate update\n        # there + in the Rust crate.\n        return CompressionPolicy(\n            live_zone_only=False,\n            cache_aligner_enabled=True,\n            volatile_token_threshold=_VOLATILE_TOKEN_THRESHOLD_PAYG,\n            max_lossy_ratio=_MAX_LOSSY_RATIO_PAYG,\n            toin_read_only=False,\n        )\n    if mode == AuthMode.SUBSCRIPTION:\n        return CompressionPolicy(\n            live_zone_only=True,\n            cache_aligner_enabled=False,\n            volatile_token_threshold=_VOLATILE_TOKEN_THRESHOLD_SUBSCRIPTION,\n            max_lossy_ratio=_MAX_LOSSY_RATIO_SUBSCRIPTION,\n            toin_read_only=True,\n        )\n    raise ValueError(f\"Unhandled AuthMode variant: {mode!r}\")\n\n\ndef policy_default_payg() -> CompressionPolicy:\n    \"\"\"The PAYG-equivalent policy used when the\n    ``HEADROOM_PROXY_AUTH_MODE_POLICY_ENFORCEMENT`` flag is disabled\n    (default in F2.1 c1-c4; flipped to enabled in c5/5).\n\n    Centralised so the proxy handlers do not duplicate the constant,\n    and so a future change to PAYG semantics propagates to both the\n    enforcement-on and enforcement-off paths.\n    \"\"\"\n    return policy_for_mode(AuthMode.PAYG)\n\n\n_ENFORCEMENT_ENV = \"HEADROOM_PROXY_AUTH_MODE_POLICY_ENFORCEMENT\"\n\n\ndef is_enforcement_enabled() -> bool:","sourceCodeStart":221,"sourceCodeEnd":257,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/transforms/compression_policy.py#L221-L257","documentation":"Raised by policy_for_mode in compression_policy.py when the passed AuthMode is neither AuthMode.PAYG nor AuthMode.SUBSCRIPTION. The function is an exhaustive match over the auth-mode enum; any other variant (or a bogus value) has no defined compression policy (live_zone_only, cache_aligner_enabled, volatile_token_threshold, max_lossy_ratio, toin_read_only all differ per mode), so it raises rather than guessing.","triggerScenarios":"Calling policy_for_mode with a new AuthMode enum member added without extending this function, or with an invalid/raw value that compares unequal to both known variants.","commonSituations":"A new auth mode (e.g. ENTERPRISE, TRIAL) is introduced in the enum but compression_policy.py is not updated; deserializing an auth mode from a config/proxy header yields an unexpected value; tests constructing AuthMode fixtures that drift.","solutions":["If you added an AuthMode variant, add a branch in policy_for_mode returning the appropriate CompressionPolicy for it.","If calling, pass only AuthMode.PAYG or AuthMode.SUBSCRIPTION (or use policy_default_payg()).","Validate the mode at the trust boundary (proxy handler) before policy lookup and reject unknown values there with a 4xx."],"exampleFix":"# before\ndef policy_for_mode(mode):\n    if mode == AuthMode.PAYG: ...\n    if mode == AuthMode.SUBSCRIPTION: ...\n    raise ValueError(f\"Unhandled AuthMode variant: {mode!r}\")\n\n# after — extend when adding a variant\nif mode == AuthMode.ENTERPRISE:\n    return CompressionPolicy(live_zone_only=True, cache_aligner_enabled=True,\n                             volatile_token_threshold=..., max_lossy_ratio=..., toin_read_only=True)","handlingStrategy":"type-guard","validationCode":"from headroom.transforms.compression_policy import policy_default_payg\nif mode not in (AuthMode.PAYG, AuthMode.SUBSCRIPTION):\n    mode = AuthMode.PAYG  # or reject at the boundary\npolicy = policy_for_mode(mode)","typeGuard":"def is_known_auth_mode(mode: AuthMode) -> bool:\n    return mode in (AuthMode.PAYG, AuthMode.SUBSCRIPTION)","tryCatchPattern":"try:\n    policy = policy_for_mode(mode)\nexcept ValueError as e:\n    if \"Unhandled AuthMode\" in str(e):\n        return policy_default_payg()  # explicit degrade, logged loudly\n    raise","preventionTips":["Reject unknown auth-mode strings at the proxy/config boundary with a 4xx.","When adding an AuthMode variant, grep for exhaustive matches and update them in the same commit.","Add an exhaustiveness test iterating over list(AuthMode)."],"tags":["enum","policy","validation","exhaustiveness"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}