headroomlabs-ai/headroom · error · ValueError

{SSE_EVENT_MAX_BYTES_ENV} must be positive, got {value}

Error message

{SSE_EVENT_MAX_BYTES_ENV} must be positive, got {value}

What it means

After parsing an integer, resolve_sse_event_max_bytes rejects values <= 0 because the per-event SSE size cap must be positive. A zero or negative cap would make every event oversized and break streaming. The check runs only when the env variable is set.

Source

Thrown at headroom/proxy/request_limit_policy.py:21

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. Set a positive byte count such as 65536.
  2. Unset the variable to use the built-in default.
  3. Do not use 0 to disable the limit; it is invalid.

Example fix

# before
export HEADROOM_PROXY_SSE_EVENT_MAX_BYTES=0

# after
export HEADROOM_PROXY_SSE_EVENT_MAX_BYTES=65536
Defensive patterns

Strategy: validation

Validate before calling

raw = os.environ.get("HEADROOM_PROXY_SSE_EVENT_MAX_BYTES")
if raw not in (None, "") and int(raw) <= 0:
    raise SystemExit("SSE_EVENT_MAX_BYTES must be positive")

Type guard

def valid_sse_cap(value: int) -> bool:
    return value > 0

Try / catch

try:
    cap = resolve_sse_event_max_bytes(raw)
except ValueError as e:
    abort_with(e)

Prevention

When it happens

Trigger: HEADROOM_PROXY_SSE_EVENT_MAX_BYTES=0 or a negative integer such as -1.

Common situations: Using 0 to mean 'disabled'; templating systems substituting an unset counter as 0; testing edge values.

Related errors

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