headroomlabs-ai/headroom · error · ValueError

Unhandled AuthMode variant: {mode!r}

Error message

Unhandled AuthMode variant: {mode!r}

What it means

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.

Source

Thrown at headroom/transforms/compression_policy.py:239

        # ``tests/test_compression_policy.py`` is the canary that
        # catches a future divergence and forces a deliberate update
        # there + in the Rust crate.
        return CompressionPolicy(
            live_zone_only=False,
            cache_aligner_enabled=True,
            volatile_token_threshold=_VOLATILE_TOKEN_THRESHOLD_PAYG,
            max_lossy_ratio=_MAX_LOSSY_RATIO_PAYG,
            toin_read_only=False,
        )
    if mode == AuthMode.SUBSCRIPTION:
        return CompressionPolicy(
            live_zone_only=True,
            cache_aligner_enabled=False,
            volatile_token_threshold=_VOLATILE_TOKEN_THRESHOLD_SUBSCRIPTION,
            max_lossy_ratio=_MAX_LOSSY_RATIO_SUBSCRIPTION,
            toin_read_only=True,
        )
    raise ValueError(f"Unhandled AuthMode variant: {mode!r}")


def policy_default_payg() -> CompressionPolicy:
    """The PAYG-equivalent policy used when the
    ``HEADROOM_PROXY_AUTH_MODE_POLICY_ENFORCEMENT`` flag is disabled
    (default in F2.1 c1-c4; flipped to enabled in c5/5).

    Centralised so the proxy handlers do not duplicate the constant,
    and so a future change to PAYG semantics propagates to both the
    enforcement-on and enforcement-off paths.
    """
    return policy_for_mode(AuthMode.PAYG)


_ENFORCEMENT_ENV = "HEADROOM_PROXY_AUTH_MODE_POLICY_ENFORCEMENT"


def is_enforcement_enabled() -> bool:

View on GitHub (pinned to 322425c43b)

Solutions

1. If you added an AuthMode variant, add a branch in policy_for_mode returning the appropriate CompressionPolicy for it.
2. If calling, pass only AuthMode.PAYG or AuthMode.SUBSCRIPTION (or use policy_default_payg()).
3. Validate the mode at the trust boundary (proxy handler) before policy lookup and reject unknown values there with a 4xx.

Example fix

# before
def policy_for_mode(mode):
    if mode == AuthMode.PAYG: ...
    if mode == AuthMode.SUBSCRIPTION: ...
    raise ValueError(f"Unhandled AuthMode variant: {mode!r}")

# after — extend when adding a variant
if mode == AuthMode.ENTERPRISE:
    return CompressionPolicy(live_zone_only=True, cache_aligner_enabled=True,
                             volatile_token_threshold=..., max_lossy_ratio=..., toin_read_only=True)

from headroom.transforms.compression_policy import policy_default_payg
if mode not in (AuthMode.PAYG, AuthMode.SUBSCRIPTION):
    mode = AuthMode.PAYG  # or reject at the boundary
policy = policy_for_mode(mode)

def is_known_auth_mode(mode: AuthMode) -> bool:
    return mode in (AuthMode.PAYG, AuthMode.SUBSCRIPTION)

try:
    policy = policy_for_mode(mode)
except ValueError as e:
    if "Unhandled AuthMode" in str(e):
        return policy_default_payg()  # explicit degrade, logged loudly
    raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• 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)}
• mode must be 'token' or 'cache'

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