sgl-project/sglang · error · ValueError

Unknown disagg_role: {role}

Error message

Unknown disagg_role: {role}

What it means

dispatch_launch routes on server_args.disagg_role: no role runs launch_server, SERVER runs the disagg server, and ENCODER/DENOISER/DECODER run role workers. Any other value falls through to 'Unknown disagg_role', indicating the parsed role string does not match any RoleType enum member expected by the router.

Source

Thrown at python/sglang/multimodal_gen/runtime/launch_server.py:809

        logger.info("Role %s shutting down.", role_type.value)
    finally:
        shutdown_scheduler_processes(role_args, processes, request_shutdown=False)


def dispatch_launch(server_args: ServerArgs):
    """Route to the correct launch function based on --disagg-role."""
    if "NCCL_NVLS_ENABLE" not in os.environ or server_args.enable_nccl_nvls:
        os.environ["NCCL_NVLS_ENABLE"] = str(int(server_args.enable_nccl_nvls))

    role = server_args.disagg_role
    if role == RoleType.MONOLITHIC:
        launch_server(server_args)
    elif role == RoleType.SERVER:
        launch_disagg_server(server_args)
    elif role in (RoleType.ENCODER, RoleType.DENOISER, RoleType.DECODER):
        launch_disagg_role(server_args)
    else:
        raise ValueError(f"Unknown disagg_role: {role}")


if __name__ == "__main__":
    server_args = prepare_server_args(sys.argv[1:])

    try:
        dispatch_launch(server_args)
    finally:
        kill_process_tree(os.getpid(), include_parent=False)

View on GitHub (pinned to 0132848349)

Solutions

1. Use a valid role: omit --disagg-role for monolithic serving, or one of server/encoder/denoiser/decoder (exact RoleType values — check `python -c "from ... import RoleType; print([r.value for r in RoleType])"`).
2. Fix typos in the flag value.
3. If you added a new RoleType, add a matching branch in dispatch_launch.

Example fix

# before
--disagg-role encoding
# after
--disagg-role encoder

from sglang.multimodal_gen.runtime.launch_server import RoleType  # adjust import path
valid = {r.value for r in RoleType} | {None}
assert role_arg in valid, f"--disagg-role must be one of {sorted(v for v in valid if v)}"

def is_valid_role(role: str | None) -> bool:
    return role is None or role in {r.value for r in RoleType}

When it happens

Trigger: Passing --disagg-role with a typo or unsupported value (e.g. --disagg-role encoding, --disagg-role worker), or a RoleType enum extended with a new member without updating dispatch_launch's if/elif chain.

Common situations: Typos in CLI flags; version skew where a script written for another branch uses role names this version doesn't support; adding a new RoleType and forgetting the dispatch arm.

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

• --disagg-server-addr is required for --disagg-role {role_typ
• kv-canary: kv_canary must be one of none/log/raise, got {mod
• rollout_sde_type must be one of {_VALID_ROLLOUT_SDE_TYPES},
• Cosmos3 action endpoint supports action_mode='policy' or 'in
• output_format must be 'list' or 'numpy'

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