headroomlabs-ai/headroom · error · ValueError

Invalid {BETA_TRACKER_MAX_SESSIONS_ENV}={normalized!r}; expe

Error message

Invalid {BETA_TRACKER_MAX_SESSIONS_ENV}={normalized!r}; expected positive int

What it means

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.

Source

Thrown at headroom/proxy/beta_header_policy.py:37

    if not normalized:
        return BETA_HEADER_STICKY_DEFAULT
    if normalized in ("enabled", "disabled"):
        return cast(BetaHeaderStickyMode, normalized)
    raise ValueError(
        f"Invalid {BETA_HEADER_STICKY_ENV}={normalized!r}; expected 'enabled' or 'disabled'"
    )


def resolve_beta_tracker_max_sessions(raw: str | None) -> int:
    """Resolve the positive LRU session bound for beta-header tracking."""

    normalized = (raw or "").strip()
    if not normalized:
        return BETA_TRACKER_MAX_SESSIONS_DEFAULT
    try:
        value = int(normalized)
    except ValueError as exc:
        raise ValueError(
            f"Invalid {BETA_TRACKER_MAX_SESSIONS_ENV}={normalized!r}; expected positive int"
        ) from exc
    if value <= 0:
        raise ValueError(
            f"Invalid {BETA_TRACKER_MAX_SESSIONS_ENV}={normalized!r}; expected positive int"
        )
    return value

View on GitHub (pinned to 322425c43b)

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.

Example fix

# before
export HEADROOM_BETA_TRACKER_MAX_SESSIONS=1k  # ValueError

# after
export HEADROOM_BETA_TRACKER_MAX_SESSIONS=1000

Defensive patterns

Strategy: validation

Validate before calling

def sessions_env_ok(raw: str | None) -> bool:
    n = (raw or "").strip()
    if not n:
        return True
    try:
        return int(n) > 0
    except ValueError:
        return False

Try / catch

try:
    limit = resolve_beta_tracker_max_sessions(os.environ["HEADROOM_BETA_TRACKER_MAX_SESSIONS"])
except ValueError as exc:
    limit = 1000
    log.warning("invalid HEADROOM_BETA_TRACKER_MAX_SESSIONS, using default: %s", exc)

Prevention

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.

When it happens

Trigger: Setting HEADROOM_BETA_TRACKER_MAX_SESSIONS to a non-integer string, e.g. '1k', '100.5', '0x10', 'many', or '' (explicitly exported empty).

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

Related errors

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