sgl-project/sglang · error · ValueError

num_draft_layers must be positive, got {num_draft_layers}.

Error message

num_draft_layers must be positive, got {num_draft_layers}.

What it means

Raised by build_target_layer_ids when num_draft_layers <= 0. The function spreads draft layers across target layer positions, so at least one draft layer is required. A non-positive draft layer count indicates the speculative draft config is malformed.

Source

Thrown at python/sglang/srt/speculative/dflash_utils.py:375

    Args:
        num_target_layers: Number of transformer layers in the runtime target model.
        num_draft_layers: Number of layers in the DFlash draft model.

    Returns:
        A list of 0-based target layer indices of length `num_draft_layers`.

    Notes:
        - DFlash uses hidden states after each selected target layer (HF-style).
        - SGLang captures "before layer i", so the model hook will typically add +1
          when mapping to capture points.
    """
    if num_target_layers <= 0:
        raise ValueError(
            f"num_target_layers must be positive, got {num_target_layers}."
        )
    if num_draft_layers <= 0:
        raise ValueError(f"num_draft_layers must be positive, got {num_draft_layers}.")

    if num_draft_layers == 1:
        return [num_target_layers // 2]

    start = 1
    end = num_target_layers - 3
    if end < start:
        raise ValueError(
            "DFlash layer selection requires num_target_layers >= 4. "
            f"Got num_target_layers={num_target_layers}."
        )

    span = end - start
    return [
        int(round(start + (i * span) / (num_draft_layers - 1)))
        for i in range(num_draft_layers)
    ]

View on GitHub (pinned to 0132848349)

Solutions

1. Set the draft layer count to >= 1 in the draft config / server args (e.g. --speculative-num-draft-tokens vs --speculative-num-steps style flags — use the one controlling draft layers).
2. Validate parse_dflash_draft_config output before launching; require_num_layers and the draft-layer field should both be positive.
3. Re-check the DFLASH draft config JSON from the model repo for the correct field names.

Example fix

# before
build_target_layer_ids(num_target_layers=32, num_draft_layers=0)
# after
build_target_layer_ids(num_target_layers=32, num_draft_layers=1)

if not isinstance(num_draft_layers, int) or num_draft_layers < 1:
    raise ValueError('num_draft_layers must be >= 1')

def is_valid_draft_layers(v) -> bool:
    return isinstance(v, int) and v >= 1

When it happens

Trigger: Calling build_target_layer_ids(num_target_layers=N, num_draft_layers=0), typically from resolve_target_layer_ids when the DFlashDraftConfig has num_draft_layers unset/0.

Common situations: Draft config JSON with speculative_num_draft_layers: 0; CLI flag --speculative-num-draft-tokens confused with draft layers and set to 0; a draft config parsed from a HF repo where the field is missing and defaulted to 0.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• num_target_layers must be positive, got {num_target_layers}.
• DFlash layer selection requires num_target_layers >= 4. Got
• {field_name} must be {comparator}, got {parsed}.
• DFLASH mask_token must be a non-empty string, got {mask_toke
• Invalid fused KV rotary/head dim pair: rotary_dim={rotary_di

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