sgl-project/sglang · error · ValueError

num_blocks must be positive

Error message

num_blocks must be positive

What it means

expand_causal_block_prompts validates that num_blocks > 0; zero or negative block counts are meaningless for causal denoising scheduling and rejected.

Source

Thrown at python/sglang/multimodal_gen/runtime/pipelines_core/stages/causal_denoising.py:66

CAUSAL_BLOCK_PROMPTS_KEY = "causal_block_prompts"
CAUSAL_SCENE_CUT_MASK_KEY = "causal_scene_cut_mask"
CAUSAL_SHOT_INDICES_KEY = "causal_shot_indices"
CausalKVCache = CausalSelfAttentionKVCache | QVGPackedCausalKVCache


def expand_causal_block_prompts(
    shot_prompts: list[str],
    *,
    num_blocks: int,
    shot_durations: list[int] | None = None,
    chunks_per_shot: int = 0,
    scene_cut_prefix: str = "",
) -> tuple[list[str], list[bool], list[int]]:
    if not shot_prompts:
        raise ValueError("shot_prompts must be non-empty")
    if num_blocks <= 0:
        raise ValueError("num_blocks must be positive")
    if shot_durations is not None and len(shot_durations) != len(shot_prompts):
        raise ValueError("shot_durations must match shot_prompts length")

    if shot_durations is not None:
        durations = shot_durations[: len(shot_prompts)]
    elif chunks_per_shot > 0:
        durations = [chunks_per_shot] * len(shot_prompts)
    else:
        base, extra = divmod(num_blocks, len(shot_prompts))
        durations = [base + (1 if i < extra else 0) for i in range(len(shot_prompts))]

    clamped: list[int] = []
    remaining = num_blocks
    for duration in durations:
        if remaining <= 0:
            break
        take = min(int(duration), remaining)
        clamped.append(take)

View on GitHub (pinned to 0132848349)

Solutions

1. Ensure num_frames >= num_frames_per_block before computing num_blocks
2. Pass num_blocks >= 1 explicitly
3. Check chunks_per_shot / durations configuration for zero-valued shots

Example fix

# before
expand_causal_block_prompts(prompts, num_blocks=len(frames)//block)
# after
expand_causal_block_prompts(prompts, num_blocks=max(1, len(frames)//block))

num_blocks = max(1, total_frames // num_frames_per_block)
assert num_blocks > 0

When it happens

Trigger: Calling expand_causal_block_prompts(prompts, num_blocks=0) or with negative num_blocks, often derived from num_frames // num_frames_per_block when num_frames < block size.

Common situations: Very short clip whose frame count is smaller than num_frames_per_block, yielding 0 blocks; misconfigured block size; off-by-one in duration math.

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

• causal block prompt count must match causal block count, got
• shot_prompts must be non-empty
• shot_durations must match shot_prompts length
• Cosmos3 action prompt list must contain only strings
• Cosmos3 batched action input requires one prompt per image,

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