sgl-project/sglang · error · ValueError
Unknown dispatch policy '{name}'. Available: {list(policies.
Error message
Unknown dispatch policy '{name}'. Available: {list(policies.keys())} What it means
Raised by create_dispatch_policy when the requested policy name string is not one of the registered policies ('round_robin', 'max_free_slots'). The factory resolves the name against a dict of policy classes and falls through to this error for unknown keys.
Source
Thrown at python/sglang/multimodal_gen/runtime/disaggregation/dispatch_policy.py:162
def select_encoder_with_capacity(self, free_slots: list[int]) -> int | None:
return self.encoder_policy.select_with_capacity(free_slots)
def select_denoiser_with_capacity(self, free_slots: list[int]) -> int | None:
return self.denoiser_policy.select_with_capacity(free_slots)
def select_decoder_with_capacity(self, free_slots: list[int]) -> int | None:
return self.decoder_policy.select_with_capacity(free_slots)
def create_dispatch_policy(name: str, num_instances: int, **kwargs) -> DispatchPolicy:
policies = {
"round_robin": RoundRobin,
"max_free_slots": MaxFreeSlotsFirst,
}
cls = policies.get(name)
if cls is None:
raise ValueError(
f"Unknown dispatch policy '{name}'. Available: {list(policies.keys())}"
)
return cls(num_instances=num_instances, **kwargs)
View on GitHub (pinned to 0132848349)
Solutions
- Use exactly one of the registered names: 'round_robin' or 'max_free_slots' (lowercase with underscores)
- Check the error message's Available list against your config value and fix casing/spelling
- If you need a custom policy, subclass DispatchPolicy and construct it directly instead of via the factory
- Pin config files to the sglang version whose policy names you verified
Example fix
# before policy = create_dispatch_policy(name="roundrobin", num_instances=4) # after policy = create_dispatch_policy(name="round_robin", num_instances=4)
Defensive patterns
Strategy: validation
Validate before calling
ALLOWED = {"round_robin", "max_free_slots"}
if policy_name not in ALLOWED:
raise ConfigError(f"dispatch policy must be one of {ALLOWED}, got {policy_name!r}")
policy = create_dispatch_policy(name=policy_name, num_instances=n, **kwargs) Prevention
- Validate policy names against the factory's available list at config load time
- Normalize config input (strip/lower) before passing to the factory
- Add a config lint test that checks every policy name used in your YAML files
When it happens
Trigger: Calling create_dispatch_policy(name=..., num_instances=..., **kwargs) with a misspelled, differently-cased, or unimplemented policy name (e.g. 'roundrobin', 'least_loaded', 'RoundRobin').
Common situations: Typos or wrong naming convention in a YAML/JSON config, a config written for a newer/older sglang version with different policy names, or assuming a policy exists that was never implemented.
Related errors
- num_instances must be >= 1, got {num_instances}
- Duplicate request_id: {request_id}
- Unknown request_id: {request_id}
- Cannot transition {request_id} from terminal state {old_stat
- Invalid transition for {request_id}: {old_state.value} -> {n
AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28).
Data as JSON: /api/errors/26e11f6e2a47b5af.
Report an issue: GitHub.