sgl-project/sglang · error · ValueError

--speculative-draft-window-size must be positive, got {}.

Error message

--speculative-draft-window-size must be positive, got {}.

What it means

--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.

Source

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

        kwargs["_configuration_file"] = override_config_file.strip()

    declare_resolution(
        server_args,
        "handle_speculative_decoding",
        speculative_algorithm=_resolve_speculative_algorithm_alias(
            cfg.speculative_algorithm,
            cfg.speculative_draft_model_path,
            trust_remote_code=cfg.trust_remote_code,
            kwargs=kwargs,
        ),
    )

    # Validate --speculative-draft-window-size once, regardless of algorithm.
    # Consumed by DFLASH (compact draft KV cache) and Llama EAGLE-3 (drafter attention SWA).
    if cfg.speculative_draft_window_size is not None:
        window_size = int(cfg.speculative_draft_window_size)
        if window_size <= 0:
            raise ValueError(
                f"--speculative-draft-window-size must be positive, got {window_size}."
            )
        declare_resolution(
            server_args,
            "handle_speculative_decoding",
            speculative_draft_window_size=window_size,
        )
        if cfg.speculative_algorithm not in ("EAGLE3", "DFLASH"):
            logger.warning(
                "--speculative-draft-window-size has no effect with "
                "speculative_algorithm=%s (honored by Llama EAGLE-3 and DFLASH only).",
                cfg.speculative_algorithm,
            )

    algo = None
    if cfg.speculative_algorithm is not None:
        from sglang.srt.speculative.spec_info import SpeculativeAlgorithm
        from sglang.srt.speculative.spec_registry import CustomSpecAlgo

View on GitHub (pinned to 0132848349)

Solutions

1. Set a positive window size (e.g. 4096 or model-appropriate value)
2. If you meant to disable the window, omit the flag entirely (None)

Example fix

# before
--speculative-draft-window-size 0
# after
--speculative-draft-window-size 4096

if args.speculative_draft_window_size is not None:
    assert int(args.speculative_draft_window_size) > 0

def valid_window(n) -> bool:
    return n is None or (isinstance(n, int) and n > 0)

When it happens

Trigger: Passing --speculative-draft-window-size 0 or a negative number in any speculative configuration.

Common situations: Scripted configs computing the window from context length arithmetic that can hit 0; disabling intent mistaken as 0.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• --speculative-draft-window-size must be >= --speculative-num
• Unknown match_type: '{match_type}'. Must be 'BFS' or 'PROB'.
• Kimi-K3 DCP + DSPARK currently requires SGLANG_RAGGED_VERIFY
• --disaggregation-decode-enable-radix-cache is incompatible w
• Gemma4AssistantForCausalLM draft requires --speculative-algo

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