sgl-project/sglang · error · ValueError

DSpark could not resolve speculative_num_draft_tokens; set -

Error message

DSpark could not resolve speculative_num_draft_tokens; set --speculative-dspark-block-size (= gamma).

What it means

After defaults and draft-config inference, DSpark still could not determine speculative_num_draft_tokens. This happens when no --speculative-dspark-block-size is given and the draft config provides no usable gamma, leaving the verify window unresolved.

Source

Thrown at python/sglang/srt/arg_groups/speculative_hook.py:506

    if gamma is not None:
        verify_window = int(gamma) + 1
        if (
            cfg.speculative_num_draft_tokens is not None
            and int(cfg.speculative_num_draft_tokens) != verify_window
        ):
            raise ValueError(
                "DSpark speculative_num_draft_tokens must equal gamma + 1 "
                f"(= {verify_window} for gamma={gamma}), but got "
                f"speculative_num_draft_tokens={cfg.speculative_num_draft_tokens}."
            )
        declare_resolution(
            server_args,
            "_handle_dspark",
            speculative_num_draft_tokens=verify_window,
        )

    if cfg.speculative_num_draft_tokens is None:
        raise ValueError(
            "DSpark could not resolve speculative_num_draft_tokens; set "
            "--speculative-dspark-block-size (= gamma)."
        )
    if int(cfg.speculative_num_draft_tokens) < 2:
        raise ValueError(
            "DSpark speculative_num_draft_tokens must be >= 2 (= gamma + 1), "
            f"got {cfg.speculative_num_draft_tokens}."
        )

    if cfg.max_running_requests is None:
        declare_resolution(
            server_args,
            "_handle_dspark",
            max_running_requests=48,
        )
        logger.warning(
            "Max running requests is reset to 48 for speculative decoding. You can override this by explicitly setting --max-running-requests."
        )

View on GitHub (pinned to 0132848349)

Solutions

1. Add --speculative-dspark-block-size (gamma), which also resolves num_draft_tokens = gamma + 1
2. Or set --speculative-num-draft-tokens explicitly
3. Check the draft checkpoint config exposes the block-size/gamma field so it can be inferred

Example fix

# before
--speculative-algorithm DSPARK --model-path M --speculative-draft-model-path D
# after
--speculative-algorithm DSPARK --model-path M --speculative-draft-model-path D --speculative-dspark-block-size 4

if args.speculative_algorithm == 'DSPARK':
    if args.speculative_dspark_block_size is None and args.speculative_num_draft_tokens is None:
        raise SystemExit('set --speculative-dspark-block-size (gamma) for DSPARK')

When it happens

Trigger: DSpark launch with neither --speculative-dspark-block-size nor a draft config from which gamma can be inferred, and no explicit --speculative-num-draft-tokens.

Common situations: Minimal launch command with only algorithm + model paths; draft checkpoint missing the gamma field in its config.json.

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

• DSpark dense speculative decoding requires setting --specula
• DSpark speculative_num_draft_tokens must equal gamma + 1 (=
• DSpark speculative_num_draft_tokens must be >= 2 (= gamma +
• Kimi-K3 DCP + DSPARK currently requires SGLANG_RAGGED_VERIFY
• DFLASH speculative decoding requires setting --speculative-d

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