{"record":{"id":"dae6fdea153f0ecd","repo":"headroomlabs-ai/headroom","slug":"invalid-beta-header-sticky-env-normalized-r-e","errorCode":null,"errorMessage":"Invalid {BETA_HEADER_STICKY_ENV}={normalized!r}; expected 'enabled' or 'disabled'","messagePattern":"Invalid (.+?)=(.+?); expected 'enabled' or 'disabled'","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"headroom/proxy/beta_header_policy.py","lineNumber":23,"sourceCode":"from typing import Literal, cast\n\nBETA_HEADER_STICKY_ENV = \"HEADROOM_BETA_HEADER_STICKY\"\nBetaHeaderStickyMode = Literal[\"enabled\", \"disabled\"]\nBETA_HEADER_STICKY_DEFAULT: BetaHeaderStickyMode = \"enabled\"\n\nBETA_TRACKER_MAX_SESSIONS_ENV = \"HEADROOM_BETA_TRACKER_MAX_SESSIONS\"\nBETA_TRACKER_MAX_SESSIONS_DEFAULT = 1000\n\n\ndef resolve_beta_header_sticky_mode(raw: str | None) -> BetaHeaderStickyMode:\n    \"\"\"Resolve beta-header stickiness mode from an environment value.\"\"\"\n\n    normalized = (raw or \"\").strip().lower()\n    if not normalized:\n        return BETA_HEADER_STICKY_DEFAULT\n    if normalized in (\"enabled\", \"disabled\"):\n        return cast(BetaHeaderStickyMode, normalized)\n    raise ValueError(\n        f\"Invalid {BETA_HEADER_STICKY_ENV}={normalized!r}; expected 'enabled' or 'disabled'\"\n    )\n\n\ndef resolve_beta_tracker_max_sessions(raw: str | None) -> int:\n    \"\"\"Resolve the positive LRU session bound for beta-header tracking.\"\"\"\n\n    normalized = (raw or \"\").strip()\n    if not normalized:\n        return BETA_TRACKER_MAX_SESSIONS_DEFAULT\n    try:\n        value = int(normalized)\n    except ValueError as exc:\n        raise ValueError(\n            f\"Invalid {BETA_TRACKER_MAX_SESSIONS_ENV}={normalized!r}; expected positive int\"\n        ) from exc\n    if value <= 0:\n        raise ValueError(","sourceCodeStart":5,"sourceCodeEnd":41,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/proxy/beta_header_policy.py#L5-L41","documentation":"resolve_beta_header_sticky_mode() reads HEADROOM_BETA_HEADER_STICKY and accepts only 'enabled' or 'disabled' (case-insensitive, whitespace-trimmed); empty/unset falls back to the default. Any other value raises ValueError at proxy startup/configuration load time, so a bad value prevents the proxy from starting rather than silently changing beta-header routing behavior.","triggerScenarios":"Setting HEADROOM_BETA_HEADER_STICKY to anything besides enabled/disabled — e.g. 'true', '1', 'on', 'yes', 'auto', or a stray shell expansion like '' after explicit export.","commonSituations":"Porting a boolean-style env var from another tool ('true'/'false' are the most common wrong values); copy-pasting a config snippet written for a different env-var dialect; values with invisible characters (quotes from a .env file parsed without quote stripping).","solutions":["Use exactly 'enabled' or 'disabled': export HEADROOM_BETA_HEADER_STICKY=enabled (case does not matter).","To get the default behavior, unset the variable entirely rather than setting it to an empty/placeholder value.","Check .env files for quotes or trailing whitespace if the value looks correct — only leading/trailing whitespace is trimmed, embedded characters are not."],"exampleFix":"# before\nexport HEADROOM_BETA_HEADER_STICKY=true  # ValueError\n\n# after\nexport HEADROOM_BETA_HEADER_STICKY=enabled","handlingStrategy":"validation","validationCode":"def sticky_mode_ok(raw: str | None) -> bool:\n    n = (raw or \"\").strip().lower()\n    return not n or n in (\"enabled\", \"disabled\")","typeGuard":"from typing import Literal\n\nBetaStickyMode = Literal[\"enabled\", \"disabled\"]\n\ndef is_sticky_mode(v: str) -> TypeGuard[BetaStickyMode]:\n    return v.strip().lower() in (\"enabled\", \"disabled\")","tryCatchPattern":"try:\n    mode = resolve_beta_header_sticky_mode(os.environ.get(\"HEADROOM_BETA_HEADER_STICKY\"))\nexcept ValueError as exc:\n    sys.exit(f\"config error: {exc}\")","preventionTips":["Treat this variable as an enum, not a boolean — never write true/false/1/0.","Add an env-var lint step to deployment scripts that whitelists known enum values.","Unset rather than empty-string the variable when the default is wanted."],"tags":["configuration","environment","validation","beta-headers"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}