sgl-project/sglang · error · ValueError

Unknown router: {name}

Error message

Unknown router: {name}

What it means

Raised by the schedule simulator CLI factory _create_router when the --router argument does not match any of the supported router names: 'random', 'round_robin', or 'sticky'. The factory maps the string to a router class implementing GPU-selection policy; unknown names indicate a typo or an unimplemented policy.

Source

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

    else:
        requests = generate_random_requests(
            num_requests=args.synth_random_num_requests,
            input_len=args.synth_random_input_len,
            output_len=args.synth_random_output_len,
            range_ratio=args.synth_random_range_ratio,
            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,

View on GitHub (pinned to 0132848349)

Solutions

1. Use one of the exact supported values: random, round_robin, sticky
2. Check spelling — underscores matter ('round_robin' not 'roundrobin')
3. If you need a new routing policy, implement a Router class and register it in _create_router

Example fix

# before
python -m ...schedule_simulator.entrypoint --router least_loaded

# after
python -m ...schedule_simulator.entrypoint --router round_robin

ROUTERS = {'random', 'round_robin', 'sticky'}
if args.router not in ROUTERS:
    parser.error(f'--router must be one of {sorted(ROUTERS)}')

def is_known_router(name: str) -> bool:
    return name in {'random', 'round_robin', 'sticky'}

try:
    router = _create_router(args.router)
except ValueError as e:
    parser.error(str(e))

When it happens

Trigger: Running the schedule simulator entrypoint with args.router set to something other than random/round_robin/sticky, e.g. --router least_loaded or a misspelling like 'roundrobin'.

Common situations: Typos in CLI flags; assuming a router exists because a sibling tool supports it; passing an empty string when the flag is optional but defaulted incorrectly.

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

• Unknown scheduler: {name}
• Unknown stop criteria: {self.stop_criteria}
• Unknown serve backend {name!r}. Available values: {available
• Multiple distributions register serve backend {name!r}: {pro
• Failed to load serve backend {name!r} from {self._entry_poin

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