sgl-project/sglang · error · ValueError

DSpark speculative_num_draft_tokens must be >= 2 (= gamma +

Error message

DSpark speculative_num_draft_tokens must be >= 2 (= gamma + 1), got {}.

What it means

DSpark verification needs at least one draft token plus the bonus token, so speculative_num_draft_tokens must be >= 2. Values below 2 degenerate to non-speculative decoding and are rejected.

Source

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

        ):
            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."
        )

    if cfg.enable_mixed_chunk:
        declare_resolution(
            server_args,
            "_handle_dspark",

View on GitHub (pinned to 0132848349)

Solutions

1. Set --speculative-num-draft-tokens >= 2 (ideally gamma+1 matching block size)
2. Set --speculative-dspark-block-size >= 1 so the window defaults to >= 2
3. Disable speculative decoding entirely if minimal speculation was the goal

Example fix

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

if args.speculative_algorithm == 'DSPARK' and int(args.speculative_num_draft_tokens or 0) < 2:
    raise SystemExit('num_draft_tokens must be >= 2 (gamma + 1)')

When it happens

Trigger: Passing --speculative-num-draft-tokens 1 (or 0) on a DSpark launch, or a draft config that resolves a window < 2.

Common situations: Users lowering draft token count to reduce memory; misunderstanding that 1 means 'no speculation' rather than minimal speculation.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• DSpark requires --speculative-dspark-block-size to be positi
• DSpark speculative_num_draft_tokens must equal gamma + 1 (=
• DSpark could not resolve speculative_num_draft_tokens; set -
• DSPARK requires explicit layer_ids for aux hidden capture.
• Unknown match_type: '{match_type}'. Must be 'BFS' or 'PROB'.

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