sgl-project/sglang · error · ValueError

DSpark dense speculative decoding requires setting --specula

Error message

DSpark dense speculative decoding requires setting --speculative-draft-model-path.

What it means

For dense targets, DSpark requires an explicit draft model path. Only if the target checkpoint bundles DSpark draft weights (detected by _target_checkpoint_bundles_dspark_draft) can the path default to --model-path; otherwise the run is rejected.

Source

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

    if cfg.speculative_draft_model_path is None:
        if _target_checkpoint_bundles_dspark_draft(server_args):
            declare_resolution(
                server_args,
                "_handle_dspark",
                speculative_draft_model_path=cfg.model_path,
            )
            declare_resolution(
                server_args,
                "_handle_dspark",
                speculative_draft_model_revision=cfg.revision,
            )
            logger.info(
                "DSpark draft weights are bundled in the target checkpoint; "
                "defaulting --speculative-draft-model-path to --model-path (%s).",
                cfg.model_path,
            )
        else:
            raise ValueError(
                "DSpark dense speculative decoding requires setting "
                "--speculative-draft-model-path."
            )

    if cfg.speculative_num_steps is None:
        declare_resolution(
            server_args,
            "_handle_dspark",
            speculative_num_steps=1,
        )
    elif int(cfg.speculative_num_steps) != 1:
        logger.warning(
            "DSpark only supports speculative_num_steps == 1; overriding speculative_num_steps=%s to 1.",
            cfg.speculative_num_steps,
        )
        declare_resolution(
            server_args,
            "_handle_dspark",

View on GitHub (pinned to 0132848349)

Solutions

1. Set --speculative-draft-model-path to a valid DSpark draft checkpoint
2. Or use a target checkpoint that bundles DSpark draft weights so the path defaults to model_path
3. Verify the checkpoint's config actually contains the DSpark draft section

Example fix

# before
--speculative-algorithm DSPARK --model-path /models/dense-target
# after
--speculative-algorithm DSPARK --model-path /models/dense-target --speculative-draft-model-path /models/dspark-draft

import os
if args.speculative_algorithm == 'DSPARK' and not args.speculative_draft_model_path:
    # only bundled checkpoints may default to model_path
    if not checkpoint_bundles_dspark_draft(args.model_path):
        raise SystemExit('DSPARK dense target needs --speculative-draft-model-path')

When it happens

Trigger: Launching DSpark with a dense target model, no --speculative-draft-model-path, and a checkpoint that does not bundle DSpark draft weights.

Common situations: Assuming the target model self-drafts (MTP-style); using an older or vanilla HF checkpoint that lacks the bundled draft component.

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

• DFLASH speculative decoding requires setting --speculative-d
• DSpark could not resolve speculative_num_draft_tokens; set -
• Kimi-K3 DCP + DSPARK currently requires SGLANG_RAGGED_VERIFY
• DSpark speculative decoding only supports CUDA or NPU device
• DSpark with dp attention requires --enable-dp-lm-head.

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