headroomlabs-ai/headroom · error · ValueError

Invalid {TOOL_INJECTION_STICKY_ENV}={normalized!r}; expected

Error message

Invalid {TOOL_INJECTION_STICKY_ENV}={normalized!r}; expected 'enabled' or 'disabled'

What it means

Raised by resolve_tool_injection_sticky_mode() when the HEADROOM_TOOL_INJECTION_STICKY environment variable is set to a value other than 'enabled' or 'disabled' (after trimming and lowercasing). The library validates this env var strictly because sticky mode controls whether memory-tool injection persists across requests. An empty/unset value is allowed and falls back to the default; only non-empty invalid strings raise.

Source

Thrown at headroom/proxy/tool_injection_policy.py:23

from typing import Literal, cast

TOOL_INJECTION_STICKY_ENV = "HEADROOM_TOOL_INJECTION_STICKY"
ToolInjectionStickyMode = Literal["enabled", "disabled"]
TOOL_INJECTION_STICKY_DEFAULT: ToolInjectionStickyMode = "enabled"

TOOL_TRACKER_MAX_SESSIONS_ENV = "HEADROOM_TOOL_TRACKER_MAX_SESSIONS"
TOOL_TRACKER_MAX_SESSIONS_DEFAULT = 1000


def resolve_tool_injection_sticky_mode(raw: str | None) -> ToolInjectionStickyMode:
    """Resolve memory-tool injection stickiness mode from an environment value."""

    normalized = (raw or "").strip().lower()
    if not normalized:
        return TOOL_INJECTION_STICKY_DEFAULT
    if normalized in ("enabled", "disabled"):
        return cast(ToolInjectionStickyMode, normalized)
    raise ValueError(
        f"Invalid {TOOL_INJECTION_STICKY_ENV}={normalized!r}; expected 'enabled' or 'disabled'"
    )


def resolve_tool_tracker_max_sessions(raw: str | None) -> int:
    """Resolve the positive LRU session bound for tool injection tracking."""

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

View on GitHub (pinned to 322425c43b)

Solutions

Set HEADROOM_TOOL_INJECTION_STICKY to exactly 'enabled' or 'disabled' (case-insensitive, surrounding whitespace is tolerated).
Unset the variable entirely to accept the default behavior.
If you need a boolean-style value, map it yourself before passing: raw = 'enabled' if flag else 'disabled'.

Example fix

# before
HEADROOM_TOOL_INJECTION_STICKY=true

# after
HEADROOM_TOOL_INJECTION_STICKY=enabled

Defensive patterns

Strategy: validation

Validate before calling

from headroom.proxy.tool_injection_policy import resolve_tool_injection_sticky_mode

raw = os.environ.get('HEADROOM_TOOL_INJECTION_STICKY')
normalized = (raw or '').strip().lower()
if normalized and normalized not in ('enabled', 'disabled'):
    raise SystemConfigError(f'bad sticky mode: {raw!r}')
mode = resolve_tool_injection_sticky_mode(raw)

Type guard

def is_valid_sticky_mode(raw: str | None) -> bool:
    normalized = (raw or '').strip().lower()
    return normalized == '' or normalized in ('enabled', 'disabled')

Try / catch

try:
    mode = resolve_tool_injection_sticky_mode(raw)
except ValueError as e:
    logger.error('config error: %s', e)
    raise SystemExit(2) from e  # fail fast at startup, not per-request

Prevention

Document the allowed values ('enabled'/'disabled') next to the env var in your deployment manifest.
Validate environment configuration once at process startup and exit early on invalid values.
Add a config lint step to CI that checks env var values against a schema.

When it happens

Trigger: Calling resolve_tool_injection_sticky_mode(raw) with e.g. 'true', 'on', '1', 'yes' — or setting HEADROOM_TOOL_INJECTION_STICKY=true in the environment before proxy startup. Any non-empty string that is not 'enabled'/'disabled' after .strip().lower() triggers it.

Common situations: Assuming boolean-style env values ('true'/'false', '1'/'0') work; a typo like 'enaabled'; copying a config from another tool that uses 'on'/'off'; leftover value from a previous deployment.

Related errors

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