{"record":{"id":"9d6b3e7605c0ecb2","repo":"sgl-project/sglang","slug":"draft-token-num-must-be-positive-got-draft-token","errorCode":null,"errorMessage":"draft_token_num must be positive, got {draft_token_num}.","messagePattern":"draft_token_num must be positive, got (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/speculative/dflash_utils.py","lineNumber":227,"sourceCode":"    next_token_logits: torch.Tensor,\n    sampling_info: Any,\n    draft_token_num: int,\n) -> None:\n    \"\"\"Apply sampling-time logit adjustments for DFlash verify in place.\n\n    This keeps v1 and v2 verify semantics aligned while letting overlap scheduling\n    use the cheaper precomputed `acc_linear_penalties` path instead of allocating a\n    repeated `[bs * draft_token_num, vocab]` penalty tensor every step.\n    \"\"\"\n    if sampling_info is None:\n        return\n    if next_token_logits.ndim != 2:\n        raise ValueError(\n            \"next_token_logits must be 2D, \"\n            f\"got shape={tuple(next_token_logits.shape)}.\"\n        )\n    if draft_token_num <= 0:\n        raise ValueError(f\"draft_token_num must be positive, got {draft_token_num}.\")\n\n    bs = len(sampling_info)\n    if next_token_logits.shape[0] != bs * draft_token_num:\n        raise ValueError(\n            \"next_token_logits row count mismatch for DFlash verify adjustments. \"\n            f\"Expected {bs * draft_token_num}, got {next_token_logits.shape[0]}.\"\n        )\n\n    if sampling_info.has_custom_logit_processor:\n        apply_custom_logit_processor(\n            next_token_logits,\n            sampling_info,\n            num_tokens_in_batch=draft_token_num,\n        )\n\n    acc_linear_penalties = getattr(sampling_info, \"acc_linear_penalties\", None)\n    penalizer = getattr(sampling_info, \"penalizer_orchestrator\", None)\n    grammar_mask = getattr(sampling_info, \"grammar_mask\", None)","sourceCodeStart":209,"sourceCodeEnd":245,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/speculative/dflash_utils.py#L209-L245","documentation":"Raised by apply_dflash_verify_logits_adjustments when the draft_token_num argument is zero or negative. DFlash speculative decoding applies per-draft-token logit adjustments during verify, so the number of draft tokens per sequence must be a positive integer. A non-positive value means the caller misconfigured the speculative draft length upstream.","triggerScenarios":"Calling apply_dflash_verify_logits_adjustments(next_token_logits, sampling_info, draft_token_num) with draft_token_num=0 or a negative value, e.g. server args --speculative-num-draft-tokens 0 or a draft config that resolved num_draft_tokens to 0.","commonSituations":"Server launched with speculative decoding enabled but speculative-num-draft-tokens set to 0; a draft config JSON with an invalid draft token count; tests constructing a DFlash verify batch with default/zeroed draft params.","solutions":["Set the draft token count to a positive value (e.g. --speculative-num-draft-tokens 8 or spec_num_draft_tokens in the draft config).","Check the resolved DFlashDraftConfig / server args before starting the server to confirm the draft length propagated correctly.","If constructing batches manually in tests, pass an explicit positive draft_token_num matching the logits rows."],"exampleFix":"# before\napply_dflash_verify_logits_adjustments(logits, sampling_info, draft_token_num=0)\n# after\napply_dflash_verify_logits_adjustments(logits, sampling_info, draft_token_num=8)","handlingStrategy":"validation","validationCode":"if draft_token_num is None or draft_token_num <= 0:\n    raise ValueError(f\"draft_token_num must be positive, got {draft_token_num!r}\")","typeGuard":"def is_positive_int(v) -> bool:\n    return isinstance(v, int) and not isinstance(v, bool) and v > 0","tryCatchPattern":null,"preventionTips":["Validate speculative draft lengths in server-args post-init, not deep in verify.","Add a unit test asserting draft_token_num >= 1 for all DFlash configs."],"tags":["speculative-decoding","dflash","argument-validation"],"backgroundTag":"invalid-argument-value","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}