headroomlabs-ai/headroom · error · ValueError

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

Error message

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

What it means

resolve_sse_event_max_bytes parses HEADROOM_PROXY_SSE_EVENT_MAX_BYTES and requires an integer string. Values like '10mb', '1.5', or empty-with-spaces fail int() and raise with the offending raw value. Unset or empty string returns the default.

Source

Thrown at headroom/proxy/request_limit_policy.py:19

"""Validation policy for proxy request and stream limits."""

from __future__ import annotations

SSE_EVENT_MAX_BYTES_ENV = "HEADROOM_SSE_BUFFER_MAX_BYTES"
SSE_EVENT_MAX_BYTES_DEFAULT = 1 * 1024 * 1024

BODY_TOO_LARGE_STATUS_ENV = "HEADROOM_PROXY_BODY_TOO_LARGE_STATUS"
BODY_TOO_LARGE_STATUS_DEFAULT = 413


def resolve_sse_event_max_bytes(raw: str | None) -> int:
    """Resolve the per-event SSE size cap from an optional env string."""
    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 plain decimal integer, e.g. 1048576.
2. Unset the variable to accept the default.
3. Convert units (MB -> bytes) before exporting.

Example fix

# before
export HEADROOM_PROXY_SSE_EVENT_MAX_BYTES=1MB

# after
export HEADROOM_PROXY_SSE_EVENT_MAX_BYTES=1048576

raw = os.environ.get("HEADROOM_PROXY_SSE_EVENT_MAX_BYTES")
if raw not in (None, ""):
    try:
        int(raw)
    except ValueError:
        raise SystemExit("SSE_EVENT_MAX_BYTES must be a plain integer")

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_sse_event_max_bytes
try:
    cap = resolve_sse_event_max_bytes(raw)
except ValueError as e:
    abort_with(e)

When it happens

Trigger: Setting HEADROOM_PROXY_SSE_EVENT_MAX_BYTES to a non-integer such as '10kb', '1e6', '1.5', or 'large'.

Common situations: Operators copying size limits formatted like nginx's client_max_body_size; expect unit suffixes that this parser does not support.

Related errors

• {SSE_EVENT_MAX_BYTES_ENV} must be positive, got {value}
• Invalid {PYTHON_FORWARDER_MODE_ENV}={normalized!r}; expected
• {BODY_TOO_LARGE_STATUS_ENV} must be an integer, got {raw!r}
• {BODY_TOO_LARGE_STATUS_ENV} must be a 4xx/5xx status, got {v
• invalid pipeline config TOML: {0}

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