sgl-project/sglang · error · ValueError

--decoupled-spec-bind-endpoint, --decoupled-spec-connect-end

Error message

--decoupled-spec-bind-endpoint, --decoupled-spec-connect-endpoints, and --decoupled-spec-rank are required for decoupled speculative decoding.

What it means

Raised when a decoupled speculative decoding role is set but any of the three required ZMQ/IPC parameters are missing. Decoupled spec decoding splits draft and verify processes, which must know their bind endpoint, connect endpoints, and rank.

Source

Thrown at python/sglang/srt/server_args.py:11213

            nccl_port = server_args.nccl_port

        if server_args.tokenizer_worker_num == 1:
            tokenizer_worker_ipc_name = None
        else:
            tokenizer_worker_ipc_name = (
                f"ipc://{tempfile.NamedTemporaryFile(delete=False).name}"
            )

        instance_id = uuid.uuid4().hex[:12]

        decoupled_spec_ipc_config = None
        if server_args.decoupled_spec_role != "null":
            if (
                server_args.decoupled_spec_bind_endpoint is None
                or server_args.decoupled_spec_connect_endpoints is None
                or server_args.decoupled_spec_rank is None
            ):
                raise ValueError(
                    "--decoupled-spec-bind-endpoint, "
                    "--decoupled-spec-connect-endpoints, and "
                    "--decoupled-spec-rank are required for decoupled speculative decoding."
                )
            decoupled_spec_ipc_config = DecoupledSpecIpcConfig(
                bind_endpoint=server_args.decoupled_spec_bind_endpoint,
                connect_endpoints=tuple(server_args.decoupled_spec_connect_endpoints),
                rank=int(server_args.decoupled_spec_rank),
            )

        if not cfg.enable_dp_attention:
            # Normal case, use IPC within a single node
            return PortArgs(
                tokenizer_ipc_name=f"ipc://{tempfile.NamedTemporaryFile(delete=False).name}",
                scheduler_input_ipc_name=f"ipc://{tempfile.NamedTemporaryFile(delete=False).name}",
                detokenizer_ipc_name=f"ipc://{tempfile.NamedTemporaryFile(delete=False).name}",
                nccl_port=nccl_port,
                rpc_ipc_name=f"ipc://{tempfile.NamedTemporaryFile(delete=False).name}",

View on GitHub (pinned to 0132848349)

Solutions

1. Provide all three flags: --decoupled-spec-bind-endpoint, --decoupled-spec-connect-endpoints, --decoupled-spec-rank
2. Or unset --decoupled-spec-role if you did not intend decoupled speculative decoding
3. Check a working launch script for the exact endpoint URI format

Example fix

# before
--decoupled-spec-role draft
# after
--decoupled-spec-role draft --decoupled-spec-bind-endpoint ipc://tmp/draft.sock --decoupled-spec-connect-endpoints '["ipc://tmp/verify.sock"]' --decoupled-spec-rank 0

if decoupled_spec_role != 'null':
    assert decoupled_spec_bind_endpoint and decoupled_spec_connect_endpoints is not None and decoupled_spec_rank is not None

When it happens

Trigger: Setting --decoupled-spec-role to something other than 'null' while omitting --decoupled-spec-bind-endpoint, --decoupled-spec-connect-endpoints, or --decoupled-spec-rank.

Common situations: Manually launching draft/verify worker processes and forgetting one endpoint flag; scripts that parameterize only some of the decoupled spec args.

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

• Invalid decoupled draft scheduler rid: {rid}
• VerifyCommit committed_tokens must be non-empty: request_id=
• Usage: sglang serve --model-path <model-name-or-path> [addit
• Error: --model-path is required. Please provide the path to
• v_cache must be provided

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