{"record":{"id":"9d0ded33ff8a6079","repo":"sgl-project/sglang","slug":"speculative-draft-window-size-must-be-positive","errorCode":null,"errorMessage":"--speculative-draft-window-size must be positive, got {}.","messagePattern":"--speculative-draft-window-size must be positive, got (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/arg_groups/speculative_hook.py","lineNumber":134,"sourceCode":"        kwargs[\"_configuration_file\"] = override_config_file.strip()\n\n    declare_resolution(\n        server_args,\n        \"handle_speculative_decoding\",\n        speculative_algorithm=_resolve_speculative_algorithm_alias(\n            cfg.speculative_algorithm,\n            cfg.speculative_draft_model_path,\n            trust_remote_code=cfg.trust_remote_code,\n            kwargs=kwargs,\n        ),\n    )\n\n    # Validate --speculative-draft-window-size once, regardless of algorithm.\n    # Consumed by DFLASH (compact draft KV cache) and Llama EAGLE-3 (drafter attention SWA).\n    if cfg.speculative_draft_window_size is not None:\n        window_size = int(cfg.speculative_draft_window_size)\n        if window_size <= 0:\n            raise ValueError(\n                f\"--speculative-draft-window-size must be positive, got {window_size}.\"\n            )\n        declare_resolution(\n            server_args,\n            \"handle_speculative_decoding\",\n            speculative_draft_window_size=window_size,\n        )\n        if cfg.speculative_algorithm not in (\"EAGLE3\", \"DFLASH\"):\n            logger.warning(\n                \"--speculative-draft-window-size has no effect with \"\n                \"speculative_algorithm=%s (honored by Llama EAGLE-3 and DFLASH only).\",\n                cfg.speculative_algorithm,\n            )\n\n    algo = None\n    if cfg.speculative_algorithm is not None:\n        from sglang.srt.speculative.spec_info import SpeculativeAlgorithm\n        from sglang.srt.speculative.spec_registry import CustomSpecAlgo","sourceCodeStart":116,"sourceCodeEnd":152,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/arg_groups/speculative_hook.py#L116-L152","documentation":"--speculative-draft-window-size is validated to be a positive integer because it sizes the draft model's sliding-window KV cache (used by DFLASH compact draft cache and Llama EAGLE-3 drafter attention). Zero or negative values are rejected before any allocation.","triggerScenarios":"Passing --speculative-draft-window-size 0 or a negative number in any speculative configuration.","commonSituations":"Scripted configs computing the window from context length arithmetic that can hit 0; disabling intent mistaken as 0.","solutions":["Set a positive window size (e.g. 4096 or model-appropriate value)","If you meant to disable the window, omit the flag entirely (None)"],"exampleFix":"# before\n--speculative-draft-window-size 0\n# after\n--speculative-draft-window-size 4096","handlingStrategy":"validation","validationCode":"if args.speculative_draft_window_size is not None:\n    assert int(args.speculative_draft_window_size) > 0","typeGuard":"def valid_window(n) -> bool:\n    return n is None or (isinstance(n, int) and n > 0)","tryCatchPattern":null,"preventionTips":["Omit the flag rather than passing 0 to 'disable'","Guard computed window values against <= 0"],"tags":["sglang","speculative-decoding","window-size","argument-validation"],"backgroundTag":"invalid-argument-value","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}