{"record":{"id":"377ae8aa960eea3a","repo":"headroomlabs-ai/headroom","slug":"sse-event-max-bytes-env-must-be-positive-got-v","errorCode":null,"errorMessage":"{SSE_EVENT_MAX_BYTES_ENV} must be positive, got {value}","messagePattern":"(.+?) must be positive, got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"headroom/proxy/request_limit_policy.py","lineNumber":21,"sourceCode":"from __future__ import annotations\n\nSSE_EVENT_MAX_BYTES_ENV = \"HEADROOM_SSE_BUFFER_MAX_BYTES\"\nSSE_EVENT_MAX_BYTES_DEFAULT = 1 * 1024 * 1024\n\nBODY_TOO_LARGE_STATUS_ENV = \"HEADROOM_PROXY_BODY_TOO_LARGE_STATUS\"\nBODY_TOO_LARGE_STATUS_DEFAULT = 413\n\n\ndef resolve_sse_event_max_bytes(raw: str | None) -> int:\n    \"\"\"Resolve the per-event SSE size cap from an optional env string.\"\"\"\n    if raw is None or raw == \"\":\n        return SSE_EVENT_MAX_BYTES_DEFAULT\n    try:\n        value = int(raw)\n    except ValueError as exc:\n        raise ValueError(f\"{SSE_EVENT_MAX_BYTES_ENV} must be an integer, got {raw!r}\") from exc\n    if value <= 0:\n        raise ValueError(f\"{SSE_EVENT_MAX_BYTES_ENV} must be positive, got {value}\")\n    return value\n\n\ndef resolve_body_too_large_status(raw: str | None) -> int:\n    \"\"\"Resolve the HTTP status code for body-too-large rejections.\"\"\"\n    if raw is None or raw == \"\":\n        return BODY_TOO_LARGE_STATUS_DEFAULT\n    try:\n        value = int(raw)\n    except ValueError as exc:\n        raise ValueError(f\"{BODY_TOO_LARGE_STATUS_ENV} must be an integer, got {raw!r}\") from exc\n    if not 400 <= value < 600:\n        raise ValueError(f\"{BODY_TOO_LARGE_STATUS_ENV} must be a 4xx/5xx status, got {value}\")\n    return value\n","sourceCodeStart":3,"sourceCodeEnd":36,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/proxy/request_limit_policy.py#L3-L36","documentation":"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.","triggerScenarios":"HEADROOM_PROXY_SSE_EVENT_MAX_BYTES=0 or a negative integer such as -1.","commonSituations":"Using 0 to mean 'disabled'; templating systems substituting an unset counter as 0; testing edge values.","solutions":["Set a positive byte count such as 65536.","Unset the variable to use the built-in default.","Do not use 0 to disable the limit; it is invalid."],"exampleFix":"# before\nexport HEADROOM_PROXY_SSE_EVENT_MAX_BYTES=0\n\n# after\nexport HEADROOM_PROXY_SSE_EVENT_MAX_BYTES=65536","handlingStrategy":"validation","validationCode":"raw = os.environ.get(\"HEADROOM_PROXY_SSE_EVENT_MAX_BYTES\")\nif raw not in (None, \"\") and int(raw) <= 0:\n    raise SystemExit(\"SSE_EVENT_MAX_BYTES must be positive\")","typeGuard":"def valid_sse_cap(value: int) -> bool:\n    return value > 0","tryCatchPattern":"try:\n    cap = resolve_sse_event_max_bytes(raw)\nexcept ValueError as e:\n    abort_with(e)","preventionTips":["Never encode 'disabled' as 0.","Validate operator envs before process launch."],"tags":["env","validation","sse"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}