sgl-project/sglang · error · ValueError

--disagg-server-addr is required for --disagg-role {role_typ

Error message

--disagg-server-addr is required for --disagg-role {role_type.value}

What it means

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().

Source

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

        launch_http_server_only(server_args)
    finally:
        diffusion_server.stop()


def launch_disagg_role(server_args: ServerArgs):
    """Launch a standalone disaggregated role instance (--disagg-role encoder/denoising/decoder).

    The instance:
    1. Binds its work PULL socket on tcp://0.0.0.0:{scheduler_port}
    2. Connects its result PUSH socket to the DiffusionServer head node
       (derived from --disagg-server-addr + role offset)
    3. Spawns GPU worker processes for the assigned role.
    """
    configure_logger(server_args)

    role_type = server_args.disagg_role
    if server_args.disagg_server_addr is None:
        raise ValueError(
            "--disagg-server-addr is required for --disagg-role " f"{role_type.value}"
        )

    # Derive endpoints
    work_endpoint = server_args.derive_pool_work_endpoint()
    result_endpoint = server_args.derive_pool_result_endpoint()

    logger.info(
        "Starting disagg role: %s, num_gpus=%d",
        role_type.value,
        server_args.num_gpus,
    )
    logger.info("  Work endpoint (bind): %s", work_endpoint)
    logger.info("  Result endpoint (connect): %s", result_endpoint)
    logger.info(
        "  P2P: hostname=%s, ib_device=%s, pool_size=%d",
        server_args.disagg_p2p_hostname,
        server_args.disagg_ib_device,

View on GitHub (pinned to 0132848349)

Solutions

1. Add --disagg-server-addr <host:port> pointing at the running disagg server (the one launched with --disagg-role server).
2. If scripting, validate the flag pair before invoking the CLI (see defense below).
3. Ensure the disagg server is already running at that address before starting role processes.

Example fix

# before
python -m sglang.multimodal_gen.runtime.launch_server --disagg-role encoder --tp 2
# after
python -m sglang.multimodal_gen.runtime.launch_server --disagg-role encoder --tp 2 \
  --disagg-server-addr 127.0.0.1:9000

assert server_args.disagg_role is not None
if server_args.disagg_role.value not in ("server",):
    if not server_args.disagg_server_addr:
        raise SystemExit("--disagg-server-addr is required for role " + server_args.disagg_role.value)

def has_server_addr(args) -> bool:
    return args.disagg_role is None or args.disagg_server_addr is not None

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• v_cache must be provided
• q must be provided unless qv is provided with only_qv=True
• mask_block_cnt and mask_block_idx must be provided for block
• LoRA batch_info must provide max_len or seg_lens.
• kv-canary: launch_canary_plan_kernels_torch_reference requir

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