{"record":{"id":"589fd80b529a5bb3","repo":"sgl-project/sglang","slug":"disagg-server-addr-is-required-for-disagg-role","errorCode":null,"errorMessage":"--disagg-server-addr is required for --disagg-role {role_type.value}","messagePattern":"--disagg-server-addr is required for --disagg-role (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/multimodal_gen/runtime/launch_server.py","lineNumber":686,"sourceCode":"        launch_http_server_only(server_args)\n    finally:\n        diffusion_server.stop()\n\n\ndef launch_disagg_role(server_args: ServerArgs):\n    \"\"\"Launch a standalone disaggregated role instance (--disagg-role encoder/denoising/decoder).\n\n    The instance:\n    1. Binds its work PULL socket on tcp://0.0.0.0:{scheduler_port}\n    2. Connects its result PUSH socket to the DiffusionServer head node\n       (derived from --disagg-server-addr + role offset)\n    3. Spawns GPU worker processes for the assigned role.\n    \"\"\"\n    configure_logger(server_args)\n\n    role_type = server_args.disagg_role\n    if server_args.disagg_server_addr is None:\n        raise ValueError(\n            \"--disagg-server-addr is required for --disagg-role \" f\"{role_type.value}\"\n        )\n\n    # Derive endpoints\n    work_endpoint = server_args.derive_pool_work_endpoint()\n    result_endpoint = server_args.derive_pool_result_endpoint()\n\n    logger.info(\n        \"Starting disagg role: %s, num_gpus=%d\",\n        role_type.value,\n        server_args.num_gpus,\n    )\n    logger.info(\"  Work endpoint (bind): %s\", work_endpoint)\n    logger.info(\"  Result endpoint (connect): %s\", result_endpoint)\n    logger.info(\n        \"  P2P: hostname=%s, ib_device=%s, pool_size=%d\",\n        server_args.disagg_p2p_hostname,\n        server_args.disagg_ib_device,","sourceCodeStart":668,"sourceCodeEnd":704,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/multimodal_gen/runtime/launch_server.py#L668-L704","documentation":"When launching SGLang multimodal generation in a disaggregated role (encoder, denoiser, or decoder), the role process needs the coordinator address of the disagg server to connect its work/result endpoints. The launcher validates that --disagg-server-addr was provided and refuses to start otherwise, because without it the role cannot derive its pool endpoints via derive_pool_work_endpoint()/derive_pool_result_endpoint().","triggerScenarios":"Running `python -m sglang.multimodal_gen.runtime.launch_server --disagg-role encoder ...` (or denoiser/decoder) without the --disagg-server-addr flag; server_args.disagg_server_addr is None at launch_disagg_role.","commonSituations":"Copy-pasting a serve command and forgetting the coordinator address; scripts that pass role flags dynamically and skip the addr for non-server roles; assumption that localhost is the default.","solutions":["Add --disagg-server-addr <host:port> pointing at the running disagg server (the one launched with --disagg-role server).","If scripting, validate the flag pair before invoking the CLI (see defense below).","Ensure the disagg server is already running at that address before starting role processes."],"exampleFix":"# before\npython -m sglang.multimodal_gen.runtime.launch_server --disagg-role encoder --tp 2\n# after\npython -m sglang.multimodal_gen.runtime.launch_server --disagg-role encoder --tp 2 \\\n  --disagg-server-addr 127.0.0.1:9000","handlingStrategy":"validation","validationCode":"assert server_args.disagg_role is not None\nif server_args.disagg_role.value not in (\"server\",):\n    if not server_args.disagg_server_addr:\n        raise SystemExit(\"--disagg-server-addr is required for role \" + server_args.disagg_role.value)","typeGuard":"def has_server_addr(args) -> bool:\n    return args.disagg_role is None or args.disagg_server_addr is not None","tryCatchPattern":null,"preventionTips":["Treat --disagg-role and --disagg-server-addr as a paired flag set in launch scripts.","Validate the pair in a preflight check before spawning the CLI."],"tags":["disaggregated-serving","cli-args","missing-argument","validation"],"backgroundTag":"missing-required-argument","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}