What causes "num_instances must be >= 1, got {num_instances}" in sgl-project/sglang?

Ensure at least one encoder/denoiser instance is configured and registered before constructing the dispatch policy

sgl-project/sglang · error · ValueError

num_instances must be >= 1, got {num_instances}

Error message

num_instances must be >= 1, got {num_instances}

What it means

Thrown by the DispatchPolicy base-class constructor when num_instances is less than 1. Dispatch policies (round_robin, max_free_slots) distribute requests across a fixed set of instances, so at least one instance is required for the policy to be meaningful.

Source

Thrown at python/sglang/multimodal_gen/runtime/disaggregation/dispatch_policy.py:14

# SPDX-License-Identifier: Apache-2.0
"""Dispatch policies for multi-instance disaggregated diffusion pipelines."""

import abc
import logging
import threading

logger = logging.getLogger(__name__)


class DispatchPolicy(abc.ABC):
    def __init__(self, num_instances: int):
        if num_instances < 1:
            raise ValueError(f"num_instances must be >= 1, got {num_instances}")
        self._num_instances = num_instances

    @property
    def num_instances(self) -> int:
        return self._num_instances

    @abc.abstractmethod
    def select(self, active_counts: list[int] | None = None) -> int: ...

    def select_with_capacity(self, free_slots: list[int]) -> int | None:
        """Select an instance that has free capacity, or None if all full."""
        if not any(s > 0 for s in free_slots):
            return None
        return self.select(active_counts=None)

    def record_completion(self, instance_id: int) -> None:
        pass

View on GitHub (pinned to 0132848349)

Solutions

Ensure at least one encoder/denoiser instance is configured and registered before constructing the dispatch policy
Log/validate the instance list length at startup and fail early with a clear message when it is empty
Check that the config key feeding num_instances (instance endpoints/hosts list) is populated and parsed correctly

Example fix

# before
policy = RoundRobin(num_instances=len(instances))  # len==0 -> ValueError

# after
assert instances, "at least one instance must be configured"
policy = RoundRobin(num_instances=max(1, len(instances)))

Defensive patterns

Strategy: validation

Validate before calling

if not instances or len(instances) < 1:
    raise ConfigError("disaggregation requires at least one instance")
policy = create_dispatch_policy(name=policy_name, num_instances=len(instances), **kwargs)

Prevention

Validate the instance list is non-empty at startup before building dispatch policies
Fail fast with a descriptive message when service discovery returns zero instances
Add config schema checks that reject empty instance arrays

When it happens

Trigger: Instantiating any DispatchPolicy subclass (directly or via create_dispatch_policy) with num_instances=0 or a negative number — typically because the instance list/config used to compute num_instances was empty.

Common situations: Starting a disaggregated multimodal runtime with zero encoder or denoiser instances registered, an empty instance config file, or an off-by-one/len() of an empty list feeding num_instances.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/7de8dac02bf17072. Report an issue: GitHub.