{"record":{"id":"b4c2ac1f3ee707ab","repo":"headroomlabs-ai/headroom","slug":"invalid-python-forwarder-mode-env-normalized-r","errorCode":null,"errorMessage":"Invalid {PYTHON_FORWARDER_MODE_ENV}={normalized!r}; expected 'byte_faithful' or 'legacy_json_kwarg'","messagePattern":"Invalid (.+?)=(.+?); expected 'byte_faithful' or 'legacy_json_kwarg'","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"headroom/proxy/python_forwarder_mode_policy.py","lineNumber":19,"sourceCode":"\"\"\"Python forwarder mode resolution policy.\"\"\"\n\nfrom __future__ import annotations\n\nfrom typing import Literal, cast\n\nPYTHON_FORWARDER_MODE_ENV = \"HEADROOM_PROXY_PYTHON_FORWARDER_MODE\"\nPythonForwarderMode = Literal[\"byte_faithful\", \"legacy_json_kwarg\"]\nPYTHON_FORWARDER_MODE_DEFAULT: PythonForwarderMode = \"byte_faithful\"\n\n\ndef resolve_python_forwarder_mode(raw: str | None) -> PythonForwarderMode:\n    \"\"\"Resolve the active Python-forwarder mode from an optional value.\"\"\"\n    normalized = (raw or \"\").strip().lower()\n    if not normalized:\n        return PYTHON_FORWARDER_MODE_DEFAULT\n    if normalized in (\"byte_faithful\", \"legacy_json_kwarg\"):\n        return cast(PythonForwarderMode, normalized)\n    raise ValueError(\n        f\"Invalid {PYTHON_FORWARDER_MODE_ENV}={normalized!r}; \"\n        \"expected 'byte_faithful' or 'legacy_json_kwarg'\"\n    )\n","sourceCodeStart":1,"sourceCodeEnd":23,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/proxy/python_forwarder_mode_policy.py#L1-L23","documentation":"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'.","triggerScenarios":"Exporting HEADROOM_PROXY_PYTHON_FORWARDER_MODE=bytefaithful, =json_kwarg, =true, or any typo; process environments managed by wrappers that inject legacy values.","commonSituations":"Renamed env values across versions; scripts from older releases; CI secrets/variables carrying stale values.","solutions":["Set the variable to exactly 'byte_faithful' or 'legacy_json_kwarg'.","Unset or blank the variable to use the default mode.","Search deployment scripts and CI variables for the stale value."],"exampleFix":"# before\nexport HEADROOM_PROXY_PYTHON_FORWARDER_MODE=bytefaithful\n\n# after\nexport HEADROOM_PROXY_PYTHON_FORWARDER_MODE=byte_faithful","handlingStrategy":"validation","validationCode":"import os\nVALID = {\"byte_faithful\", \"legacy_json_kwarg\"}\nmode = (os.environ.get(\"HEADROOM_PROXY_PYTHON_FORWARDER_MODE\") or \"\").strip().lower()\nif mode and mode not in VALID:\n    raise SystemExit(f\"mode must be one of {sorted(VALID)}\")","typeGuard":"def is_forwarder_mode(v: str) -> bool:\n    return v.strip().lower() in {\"byte_faithful\", \"legacy_json_kwarg\"}","tryCatchPattern":"from headroom.proxy.python_forwarder_mode_policy import resolve_python_forwarder_mode\ntry:\n    mode = resolve_python_forwarder_mode(raw)\nexcept ValueError as e:\n    abort_with(e)","preventionTips":["Pin exact literal values in deploy scripts.","Add an env-var lint step for HEADROOM_PROXY_* names after upgrades."],"tags":["env","config","validation"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}