headroomlabs-ai/headroom · error · ValueError

{BODY_TOO_LARGE_STATUS_ENV} must be a 4xx/5xx status, got {v

Error message

{BODY_TOO_LARGE_STATUS_ENV} must be a 4xx/5xx status, got {value}

What it means

resolve_body_too_large_status restricts the body-too-large rejection status to the 400-599 range, because it must be a real client/server error code the proxy returns. Codes like 200, 307, 399, 600, or negatives are rejected at startup.

Source

Thrown at headroom/proxy/request_limit_policy.py:34

    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. Choose a 4xx or 5xx code, typically 413.
2. Unset the variable for the default.
3. Validate operator-supplied statuses against the 400-599 range before deploy.

Example fix

# before
export HEADROOM_PROXY_BODY_TOO_LARGE_STATUS=200

# after
export HEADROOM_PROXY_BODY_TOO_LARGE_STATUS=413

raw = os.environ.get("HEADROOM_PROXY_BODY_TOO_LARGE_STATUS")
if raw not in (None, "") and not 400 <= int(raw) < 600:
    raise SystemExit("status must be 4xx/5xx")

def is_error_status(code: int) -> bool:
    return 400 <= code < 600

try:
    status = resolve_body_too_large_status(raw)
except ValueError as e:
    abort_with(e)

When it happens

Trigger: HEADROOM_PROXY_BODY_TOO_LARGE_STATUS set to 200, 301, 399, 600, or any value outside 400 <= value < 600.

Common situations: Using an informational/success code to 'pass through'; typos such as 41 or 4313; testing unusual status handling.

Related errors

• {BODY_TOO_LARGE_STATUS_ENV} must be an integer, got {raw!r}
• 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/8c6223c1793049e9. Report an issue: GitHub.