headroomlabs-ai/headroom · error · ValueError

worker_processes must be >= 1

Error message

worker_processes must be >= 1

What it means

Error "worker_processes must be >= 1" thrown in headroomlabs-ai/headroom.

Source

Thrown at headroom/proxy/models.py:518

    # ``HeadroomProxy._run_compression_in_executor``.
    compression_max_workers: int | None = None

    # Number of built-in uvicorn worker processes sharing this listen socket.
    # Kept at the end to avoid shifting existing positional constructor fields.
    # Process-local runtime hot reload is unsafe above one worker because only
    # the worker receiving the admin request would observe the update.
    worker_processes: int = 1

    def __post_init__(self, smart_routing: bool | None = None) -> None:
        if self.rollout is None:
            self.rollout = resolve_rollout()
        # ``read_maturation`` remains a concrete, already-resolved runtime
        # setting for programmatic/config-file callers.  The CLI composition
        # root derives it from this same snapshot before constructing the
        # config; rewriting it here would resolve policy a second time and
        # break explicit non-CLI configuration.
        if self.worker_processes < 1:
            raise ValueError("worker_processes must be >= 1")
        if self.retry_enabled and self.retry_max_attempts < 1:
            raise ValueError("retry_max_attempts must be >= 1 when retry_enabled=True")
        # A 0 (or negative) requests-per-minute limit divides by zero in the
        # token-bucket wait computation (rate_limit_policy.consume_from_bucket),
        # 500-ing every request. The CLI already guards this with IntRange(min=1);
        # fail fast here too so the JSON/programmatic config paths can't produce a
        # limiter that crashes at request time. Only matters when limiting is on.
        if self.rate_limit_enabled and self.rate_limit_requests_per_minute < 1:
            raise ValueError(
                "rate_limit_requests_per_minute must be >= 1 when rate_limit_enabled=True"
            )

    @property
    def provider_api_overrides(self) -> ProviderApiOverrides:
        """Return provider API URL overrides as a dedicated provider config object."""
        return ProviderApiOverrides(
            anthropic=self.anthropic_api_url,
            openai=self.openai_api_url,

View on GitHub (pinned to 322425c43b)

Solutions

1. Set worker_processes to an integer >= 1 in the proxy config
2. Remove the worker_processes override to use the default

When it happens

Trigger: Raised during proxy config validation when worker_processes is set to zero or a negative value.

Common situations: See trigger scenarios.

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