{"record":{"id":"f5ce4e40c4e3f1e6","repo":"headroomlabs-ai/headroom","slug":"invalid-beta-tracker-max-sessions-env-normalize","errorCode":null,"errorMessage":"Invalid {BETA_TRACKER_MAX_SESSIONS_ENV}={normalized!r}; expected positive int","messagePattern":"Invalid (.+?)=(.+?); expected positive int","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"headroom/proxy/beta_header_policy.py","lineNumber":37,"sourceCode":"    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(\n            f\"Invalid {BETA_TRACKER_MAX_SESSIONS_ENV}={normalized!r}; expected positive int\"\n        )\n    return value\n","sourceCodeStart":19,"sourceCodeEnd":45,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/proxy/beta_header_policy.py#L19-L45","documentation":"resolve_beta_tracker_max_sessions() parses HEADROOM_BETA_TRACKER_MAX_SESSIONS as an int. This raise site is the int() failure branch: the trimmed value is not parseable as an integer at all (letters, floats like '100.5', empty-after-export). It fires during configuration resolution, i.e. typically at proxy startup.","triggerScenarios":"Setting HEADROOM_BETA_TRACKER_MAX_SESSIONS to a non-integer string, e.g. '1k', '100.5', '0x10', 'many', or '' (explicitly exported empty).","commonSituations":"Using human shorthand ('2k') or a float where an int is required; inheriting a value formatted for a different tool (YAML unquoted 1000.0); a typo in the number.","solutions":["Set a plain positive integer: export HEADROOM_BETA_TRACKER_MAX_SESSIONS=2000.","Remove unit suffixes and decimal points — '2k' and '1000.0' are invalid; write 2000 and 1000.","Unset the variable to fall back to the default of 1000 sessions."],"exampleFix":"# before\nexport HEADROOM_BETA_TRACKER_MAX_SESSIONS=1k  # ValueError\n\n# after\nexport HEADROOM_BETA_TRACKER_MAX_SESSIONS=1000","handlingStrategy":"validation","validationCode":"def sessions_env_ok(raw: str | None) -> bool:\n    n = (raw or \"\").strip()\n    if not n:\n        return True\n    try:\n        return int(n) > 0\n    except ValueError:\n        return False","typeGuard":null,"tryCatchPattern":"try:\n    limit = resolve_beta_tracker_max_sessions(os.environ[\"HEADROOM_BETA_TRACKER_MAX_SESSIONS\"])\nexcept ValueError as exc:\n    limit = 1000\n    log.warning(\"invalid HEADROOM_BETA_TRACKER_MAX_SESSIONS, using default: %s\", exc)","preventionTips":["Only plain base-10 integers in this env var — no suffixes, floats, or quotes.","Validate env vars centrally in a config loader at process start instead of deep in library code."],"tags":["configuration","environment","validation","parsing"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}