headroomlabs-ai/headroom · error · ValueError

{BODY_TOO_LARGE_STATUS_ENV} must be an integer, got {raw!r}

Error message

{BODY_TOO_LARGE_STATUS_ENV} must be an integer, got {raw!r}

What it means

resolve_body_too_large_status parses HEADROOM_PROXY_BODY_TOO_LARGE_STATUS and requires an integer HTTP status string. Non-integer values like '413.0', 'Payload Too Large', or '4xx' fail int() and raise with the raw value. Unset or empty returns the default 413.

Source

Thrown at headroom/proxy/request_limit_policy.py:32

    if raw is None or raw == "":
        return SSE_EVENT_MAX_BYTES_DEFAULT
    try:
        value = int(raw)
    except ValueError as exc:
        raise ValueError(f"{SSE_EVENT_MAX_BYTES_ENV} must be an integer, got {raw!r}") from exc
    if value <= 0:
        raise ValueError(f"{SSE_EVENT_MAX_BYTES_ENV} must be positive, got {value}")
    return value


def resolve_body_too_large_status(raw: str | None) -> int:
    """Resolve the HTTP status code for body-too-large rejections."""
    if raw is None or raw == "":
        return BODY_TOO_LARGE_STATUS_DEFAULT
    try:
        value = int(raw)
    except ValueError as exc:
        raise ValueError(f"{BODY_TOO_LARGE_STATUS_ENV} must be an integer, got {raw!r}") from exc
    if not 400 <= value < 600:
        raise ValueError(f"{BODY_TOO_LARGE_STATUS_ENV} must be a 4xx/5xx status, got {value}")
    return value

View on GitHub (pinned to 322425c43b)

Solutions

1. Use a numeric status code such as 413 or 400.
2. Unset the variable to keep the default 413.
3. Remove quotes around numeric values in env files if a parser stores '413' correctly but letters do not.

Example fix

# before
export HEADROOM_PROXY_BODY_TOO_LARGE_STATUS=Payload Too Large

# after
export HEADROOM_PROXY_BODY_TOO_LARGE_STATUS=413

raw = os.environ.get("HEADROOM_PROXY_BODY_TOO_LARGE_STATUS")
if raw not in (None, ""):
    try:
        int(raw)
    except ValueError:
        raise SystemExit("BODY_TOO_LARGE_STATUS must be numeric")

def parses_as_int(raw: str | None) -> bool:
    if raw in (None, ""):
        return True
    try:
        int(raw)
        return True
    except ValueError:
        return False

from headroom.proxy.request_limit_policy import resolve_body_too_large_status
try:
    status = resolve_body_too_large_status(raw)
except ValueError as e:
    abort_with(e)

When it happens

Trigger: Setting HEADROOM_PROXY_BODY_TOO_LARGE_STATUS to a reason phrase, float, or typo like '14'.

Common situations: Copy-pasting HTTP reason phrases; configs migrated from tools that accept symbolic statuses.

Related errors

• {BODY_TOO_LARGE_STATUS_ENV} must be a 4xx/5xx status, got {v
• Invalid {PYTHON_FORWARDER_MODE_ENV}={normalized!r}; expected
• {SSE_EVENT_MAX_BYTES_ENV} must be an integer, got {raw!r}
• {SSE_EVENT_MAX_BYTES_ENV} must be positive, got {value}
• hash required

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