{"record":{"id":"44261ae7e130c55e","repo":"sgl-project/sglang","slug":"dflash-speculative-decoding-requires-setting-spe","errorCode":null,"errorMessage":"DFLASH speculative decoding requires setting --speculative-draft-model-path.","messagePattern":"DFLASH speculative decoding requires setting --speculative-draft-model-path\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/arg_groups/speculative_hook.py","lineNumber":205,"sourceCode":"    from sglang.srt.arg_groups.overrides import resolved_view\n\n    if not (cfg.device.startswith(\"cuda\") or cfg.device == \"npu\"):\n        raise ValueError(\n            \"DFLASH speculative decoding only supports CUDA and NPU devices.\"\n        )\n\n    if resolved_view(server_args).enable_dp_attention:\n        raise ValueError(\n            \"Currently DFLASH speculative decoding does not support dp attention.\"\n        )\n\n    if cfg.pp_size != 1:\n        raise ValueError(\n            \"Currently DFLASH speculative decoding only supports pp_size == 1.\"\n        )\n\n    if cfg.speculative_draft_model_path is None:\n        raise ValueError(\n            \"DFLASH speculative decoding requires setting --speculative-draft-model-path.\"\n        )\n\n    # DFLASH does not use EAGLE-style `num_steps`/`topk`, but those fields still\n    # affect generic scheduler/KV-cache accounting (buffer sizing, KV freeing,\n    # RoPE reservation). Force them to 1 to avoid surprising memory behavior.\n    #\n    # For DFlash, the natural unit is `block_size` (verify window length).\n    if cfg.speculative_num_steps is None:\n        declare_resolution(\n            server_args,\n            \"_handle_dflash\",\n            speculative_num_steps=1,\n        )\n    elif int(cfg.speculative_num_steps) != 1:\n        logger.warning(\n            \"DFLASH only supports speculative_num_steps == 1; overriding speculative_num_steps=%s to 1.\",\n            cfg.speculative_num_steps,","sourceCodeStart":187,"sourceCodeEnd":223,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/arg_groups/speculative_hook.py#L187-L223","documentation":"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.","triggerScenarios":"Launching with speculative_algorithm=DFLASH without --speculative-draft-model-path (and no bundled-draft detection for DFLASH).","commonSituations":"Assuming DFLASH behaves like NEXTN/MTP where the draft weights ship inside the target checkpoint and no draft path is needed.","solutions":["Add --speculative-draft-model-path /path/to/draft/model","Verify the path exists and is a loadable draft checkpoint","Confirm the draft model matches the target tokenizer/architecture"],"exampleFix":"# before\n--speculative-algorithm DFLASH\n# after\n--speculative-algorithm DFLASH --speculative-draft-model-path /models/dflash-draft","handlingStrategy":"validation","validationCode":"if args.speculative_algorithm == 'DFLASH' and not args.speculative_draft_model_path:\n    raise SystemExit('DFLASH requires --speculative-draft-model-path')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Prepare the draft checkpoint path in the same config as the algorithm flag","Validate that the draft path exists on all nodes before launch"],"tags":["speculative-decoding","dflash","draft-model","missing-argument"],"backgroundTag":"missing-required-argument","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}