What causes "Unknown scheduler: {name}" in sgl-project/sglang?

Use --scheduler fifo (currently the only supported value)

sgl-project/sglang · error · ValueError

Unknown scheduler: {name}

Error message

Unknown scheduler: {name}

What it means

Raised by the schedule simulator CLI factory _create_scheduler when the --scheduler argument is not 'fifo', the only implemented scheduling policy. The factory pattern means any new policy must be explicitly added; everything else falls through to this ValueError.

Source

Thrown at python/sglang/srt/debug_utils/schedule_simulator/entrypoint.py:128

            seed=args.synth_seed,
        )
    return requests


def _create_router(name: str, total_gpus: int):
    if name == "random":
        return RandomRouter(total_gpus)
    if name == "round_robin":
        return RoundRobinRouter(total_gpus)
    if name == "sticky":
        return StickyRouter(total_gpus)
    raise ValueError(f"Unknown router: {name}")


def _create_scheduler(name: str):
    if name == "fifo":
        return FIFOScheduler()
    raise ValueError(f"Unknown scheduler: {name}")


def main(args: argparse.Namespace) -> SimulationResult:
    if args.synth_seed is not None:
        random.seed(args.synth_seed)
    requests = _load_requests(args)
    total_gpus = args.num_gpus_per_engine * args.num_engines
    router = _create_router(args.router, total_gpus)
    scheduler = _create_scheduler(args.scheduler)

    sim = Simulator(
        num_gpus_per_engine=args.num_gpus_per_engine,
        router=router,
        scheduler=scheduler,
        recorders=[
            BatchSizeBalancednessRecorder(),
            AttentionComputeBalancednessRecorder(),
            AvgBatchSizeRecorder(),

View on GitHub (pinned to 0132848349)

Solutions

Use --scheduler fifo (currently the only supported value)
Check for typos and shell-variable expansion issues (empty string)
Implement and register a new scheduler class in _create_scheduler if you need another policy

Example fix

# before
python -m ...schedule_simulator.entrypoint --scheduler priority

# after
python -m ...schedule_simulator.entrypoint --scheduler fifo

Defensive patterns

Strategy: validation

Validate before calling

if args.scheduler != 'fifo':
    parser.error("--scheduler currently supports only 'fifo'")

Type guard

def is_known_scheduler(name: str) -> bool:
    return name == 'fifo'

Try / catch

try:
    sched = _create_scheduler(args.scheduler)
except ValueError as e:
    parser.error(str(e))

Prevention

Use argparse choices=['fifo']
Watch for empty-string shell variables passed as the flag value

When it happens

Trigger: Running the simulator with args.scheduler set to anything other than 'fifo' (e.g. --scheduler lifo, --scheduler priority).

Common situations: Typos in CLI flags; expecting priority or SJF policies that the simulator does not implement yet; scripting the CLI with an unquoted/empty variable.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

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