{"record":{"id":"fc929c57cea6a7f2","repo":"sgl-project/sglang","slug":"unknown-disagg-role-role","errorCode":null,"errorMessage":"Unknown disagg_role: {role}","messagePattern":"Unknown disagg_role: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/launch_server.py","lineNumber":809,"sourceCode":"        logger.info(\"Role %s shutting down.\", role_type.value)\n    finally:\n        shutdown_scheduler_processes(role_args, processes, request_shutdown=False)\n\n\ndef dispatch_launch(server_args: ServerArgs):\n    \"\"\"Route to the correct launch function based on --disagg-role.\"\"\"\n    if \"NCCL_NVLS_ENABLE\" not in os.environ or server_args.enable_nccl_nvls:\n        os.environ[\"NCCL_NVLS_ENABLE\"] = str(int(server_args.enable_nccl_nvls))\n\n    role = server_args.disagg_role\n    if role == RoleType.MONOLITHIC:\n        launch_server(server_args)\n    elif role == RoleType.SERVER:\n        launch_disagg_server(server_args)\n    elif role in (RoleType.ENCODER, RoleType.DENOISER, RoleType.DECODER):\n        launch_disagg_role(server_args)\n    else:\n        raise ValueError(f\"Unknown disagg_role: {role}\")\n\n\nif __name__ == \"__main__\":\n    server_args = prepare_server_args(sys.argv[1:])\n\n    try:\n        dispatch_launch(server_args)\n    finally:\n        kill_process_tree(os.getpid(), include_parent=False)\n","sourceCodeStart":791,"sourceCodeEnd":819,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/launch_server.py#L791-L819","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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])\"`).","Fix typos in the flag value.","If you added a new RoleType, add a matching branch in dispatch_launch."],"exampleFix":"# before\n--disagg-role encoding\n# after\n--disagg-role encoder","handlingStrategy":"validation","validationCode":"from sglang.multimodal_gen.runtime.launch_server import RoleType  # adjust import path\nvalid = {r.value for r in RoleType} | {None}\nassert role_arg in valid, f\"--disagg-role must be one of {sorted(v for v in valid if v)}\"","typeGuard":"def is_valid_role(role: str | None) -> bool:\n    return role is None or role in {r.value for r in RoleType}","tryCatchPattern":null,"preventionTips":["Centralize role strings as constants shared by scripts and configs.","Fail fast on unknown CLI enum values before spawning GPU processes."],"tags":["cli-args","dispatch","enum-validation","disaggregated-serving"],"backgroundTag":"invalid-enum-value","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}