sgl-project/sglang · error · ValueError

DFLASH requires --speculative-dflash-block-size to be positi

Error message

DFLASH requires --speculative-dflash-block-size to be positive, got {}.

What it means

The DFLASH block size controls how many tokens are drafted/verified per block and must be a positive integer. A zero or negative value breaks scheduler/KV-cache accounting, so it is rejected during arg validation.

Source

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

        declare_resolution(
            server_args,
            "_handle_dflash",
            speculative_eagle_topk=1,
        )
    elif int(cfg.speculative_eagle_topk) != 1:
        logger.warning(
            "DFLASH only supports speculative_eagle_topk == 1; overriding speculative_eagle_topk=%s to 1.",
            cfg.speculative_eagle_topk,
        )
        declare_resolution(
            server_args,
            "_handle_dflash",
            speculative_eagle_topk=1,
        )

    if cfg.speculative_dflash_block_size is not None:
        if int(cfg.speculative_dflash_block_size) <= 0:
            raise ValueError(
                "DFLASH requires --speculative-dflash-block-size to be positive, "
                f"got {cfg.speculative_dflash_block_size}."
            )
        if cfg.speculative_num_draft_tokens is not None and int(
            cfg.speculative_num_draft_tokens
        ) != int(cfg.speculative_dflash_block_size):
            raise ValueError(
                "Both --speculative-num-draft-tokens and --speculative-dflash-block-size are set "
                "but they differ. For DFLASH they must match. "
                f"speculative_num_draft_tokens={cfg.speculative_num_draft_tokens}, "
                f"speculative_dflash_block_size={cfg.speculative_dflash_block_size}."
            )
        declare_resolution(
            server_args,
            "_handle_dflash",
            speculative_num_draft_tokens=int(cfg.speculative_dflash_block_size),
        )

View on GitHub (pinned to 0132848349)

Solutions

1. Set --speculative-dflash-block-size to a positive integer (e.g. 8 or 16)
2. Omit the flag entirely if you want the default/inferred block size
3. Check the value is not coming from a misconfigured env var or YAML preset

Example fix

# before
--speculative-dflash-block-size 0
# after
--speculative-dflash-block-size 16

if args.speculative_dflash_block_size is not None and int(args.speculative_dflash_block_size) <= 0:
    raise SystemExit('dflash block size must be positive')

When it happens

Trigger: Passing --speculative-dflash-block-size 0 or a negative number (possibly via a config template with an unset/placeholder value).

Common situations: Templated launch scripts that default the flag to 0 to mean 'auto'; typo'd values; env-var interpolation producing 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

• Both --speculative-num-draft-tokens and --speculative-dflash
• --speculative-draft-window-size must be >= --speculative-num
• DSpark requires --speculative-dspark-block-size to be positi
• draft_token_num must be positive, got {draft_token_num}.
• Unknown match_type: '{match_type}'. Must be 'BFS' or 'PROB'.

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