sgl-project/sglang · error · ValueError

DSpark speculative_num_draft_tokens must equal gamma + 1 (=

Error message

DSpark speculative_num_draft_tokens must equal gamma + 1 (= {} for gamma={}), but got speculative_num_draft_tokens={}.

What it means

DSpark requires speculative_num_draft_tokens to equal gamma + 1, where gamma is --speculative-dspark-block-size. If the user sets num_draft_tokens to any other value, the invariant is violated and rejected.

Source

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

            )
        gamma = int(cfg.speculative_dspark_block_size)
    else:
        if draft_config is not None:
            gamma = draft_config.resolve_gamma(default=None)
        if gamma is None and cfg.speculative_num_draft_tokens is None:
            gamma = DEFAULT_DSPARK_GAMMA
            logger.warning(
                "DSpark gamma is not set; defaulting to %d.",
                gamma,
            )

    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), "

View on GitHub (pinned to 0132848349)

Solutions

1. Remove --speculative-num-draft-tokens and let DSpark default it to gamma+1
2. Or set it explicitly to gamma + 1 (e.g. block size 4 -> 5)
3. Keep a single source of truth: only set --speculative-dspark-block-size

Example fix

# before
--speculative-dspark-block-size 4 --speculative-num-draft-tokens 8
# after
--speculative-dspark-block-size 4 --speculative-num-draft-tokens 5

g = args.speculative_dspark_block_size
if g is not None and args.speculative_num_draft_tokens is not None:
    if int(args.speculative_num_draft_tokens) != int(g) + 1:
        raise SystemExit('num_draft_tokens must be gamma + 1')

When it happens

Trigger: Passing both --speculative-dspark-block-size G and --speculative-num-draft-tokens N where N != G + 1.

Common situations: Reusing EAGLE-style flags where num_draft_tokens = steps*topk + 1 and can exceed gamma+1; stale num_draft_tokens after changing block size.

Related errors

• DSpark ignores --speculative-moe-a2a-backend; with dp attent
• DSpark could not resolve speculative_num_draft_tokens; set -
• DSpark speculative_num_draft_tokens must be >= 2 (= gamma +
• Kimi-K3 DCP + DSPARK currently requires SGLANG_RAGGED_VERIFY
• Both --speculative-num-draft-tokens and --speculative-dflash

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