headroomlabs-ai/headroom · error · ValueError

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

Error message

Invalid {PYTHON_FORWARDER_MODE_ENV}={normalized!r}; expected 'byte_faithful' or 'legacy_json_kwarg'

What it means

resolve_python_forwarder_mode parses HEADROOM_PROXY_PYTHON_FORWARDER_MODE and only accepts the literals 'byte_faithful' or 'legacy_json_kwarg' (case-insensitive after trimming). Any other non-empty value raises rather than silently falling back, per the no-silent-fallback policy. An unset or blank value returns the default 'byte_faithful'.

Source

Thrown at headroom/proxy/python_forwarder_mode_policy.py:19

"""Python forwarder mode resolution policy."""

from __future__ import annotations

from typing import Literal, cast

PYTHON_FORWARDER_MODE_ENV = "HEADROOM_PROXY_PYTHON_FORWARDER_MODE"
PythonForwarderMode = Literal["byte_faithful", "legacy_json_kwarg"]
PYTHON_FORWARDER_MODE_DEFAULT: PythonForwarderMode = "byte_faithful"


def resolve_python_forwarder_mode(raw: str | None) -> PythonForwarderMode:
    """Resolve the active Python-forwarder mode from an optional value."""
    normalized = (raw or "").strip().lower()
    if not normalized:
        return PYTHON_FORWARDER_MODE_DEFAULT
    if normalized in ("byte_faithful", "legacy_json_kwarg"):
        return cast(PythonForwarderMode, normalized)
    raise ValueError(
        f"Invalid {PYTHON_FORWARDER_MODE_ENV}={normalized!r}; "
        "expected 'byte_faithful' or 'legacy_json_kwarg'"
    )

View on GitHub (pinned to 322425c43b)

Solutions

1. Set the variable to exactly 'byte_faithful' or 'legacy_json_kwarg'.
2. Unset or blank the variable to use the default mode.
3. Search deployment scripts and CI variables for the stale value.

Example fix

# before
export HEADROOM_PROXY_PYTHON_FORWARDER_MODE=bytefaithful

# after
export HEADROOM_PROXY_PYTHON_FORWARDER_MODE=byte_faithful

import os
VALID = {"byte_faithful", "legacy_json_kwarg"}
mode = (os.environ.get("HEADROOM_PROXY_PYTHON_FORWARDER_MODE") or "").strip().lower()
if mode and mode not in VALID:
    raise SystemExit(f"mode must be one of {sorted(VALID)}")

def is_forwarder_mode(v: str) -> bool:
    return v.strip().lower() in {"byte_faithful", "legacy_json_kwarg"}

from headroom.proxy.python_forwarder_mode_policy import resolve_python_forwarder_mode
try:
    mode = resolve_python_forwarder_mode(raw)
except ValueError as e:
    abort_with(e)

When it happens

Trigger: Exporting HEADROOM_PROXY_PYTHON_FORWARDER_MODE=bytefaithful, =json_kwarg, =true, or any typo; process environments managed by wrappers that inject legacy values.

Common situations: Renamed env values across versions; scripts from older releases; CI secrets/variables carrying stale values.

Related errors

• Unknown provider: {self.provider}
• api_key is required for cloud mode
• default_importance must be 0.0-1.0, got {self.default_import
• dedup_similarity_threshold must be 0.0-1.0, got {self.dedup_
• vector_dimension must be positive, got {self.vector_dimensio

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