sgl-project/sglang · error · ValueError

DFLASH speculative decoding requires setting --speculative-d

Error message

DFLASH speculative decoding requires setting --speculative-draft-model-path.

What it means

DFLASH needs a separate draft model to propose tokens; there is no self-drafting fallback. The hook requires --speculative-draft-model-path to be set explicitly.

Source

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

    from sglang.srt.arg_groups.overrides import resolved_view

    if not (cfg.device.startswith("cuda") or cfg.device == "npu"):
        raise ValueError(
            "DFLASH speculative decoding only supports CUDA and NPU devices."
        )

    if resolved_view(server_args).enable_dp_attention:
        raise ValueError(
            "Currently DFLASH speculative decoding does not support dp attention."
        )

    if cfg.pp_size != 1:
        raise ValueError(
            "Currently DFLASH speculative decoding only supports pp_size == 1."
        )

    if cfg.speculative_draft_model_path is None:
        raise ValueError(
            "DFLASH speculative decoding requires setting --speculative-draft-model-path."
        )

    # DFLASH does not use EAGLE-style `num_steps`/`topk`, but those fields still
    # affect generic scheduler/KV-cache accounting (buffer sizing, KV freeing,
    # RoPE reservation). Force them to 1 to avoid surprising memory behavior.
    #
    # For DFlash, the natural unit is `block_size` (verify window length).
    if cfg.speculative_num_steps is None:
        declare_resolution(
            server_args,
            "_handle_dflash",
            speculative_num_steps=1,
        )
    elif int(cfg.speculative_num_steps) != 1:
        logger.warning(
            "DFLASH only supports speculative_num_steps == 1; overriding speculative_num_steps=%s to 1.",
            cfg.speculative_num_steps,

View on GitHub (pinned to 0132848349)

Solutions

1. Add --speculative-draft-model-path /path/to/draft/model
2. Verify the path exists and is a loadable draft checkpoint
3. Confirm the draft model matches the target tokenizer/architecture

Example fix

# before
--speculative-algorithm DFLASH
# after
--speculative-algorithm DFLASH --speculative-draft-model-path /models/dflash-draft

if args.speculative_algorithm == 'DFLASH' and not args.speculative_draft_model_path:
    raise SystemExit('DFLASH requires --speculative-draft-model-path')

When it happens

Trigger: Launching with speculative_algorithm=DFLASH without --speculative-draft-model-path (and no bundled-draft detection for DFLASH).

Common situations: Assuming DFLASH behaves like NEXTN/MTP where the draft weights ship inside the target checkpoint and no draft path is needed.

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
• DFLASH speculative decoding only supports CUDA and NPU devic
• Currently DFLASH speculative decoding does not support dp at
• Currently DFLASH speculative decoding only supports pp_size
• DFLASH requires --speculative-dflash-block-size to be positi

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