sgl-project/sglang · error · ValueError

mask_block_cnt and mask_block_idx must be provided for block

Error message

mask_block_cnt and mask_block_idx must be provided for block sparsity.

What it means

Raised during shape inference when mask_block_idx (and cnt) is missing from the block-sparse tensor bundle. Block sparsity cannot operate without at least the mask indices/counts.

Source

Thrown at python/sglang/kernels/ops/attention/flash_attn/cute/block_sparsity.py:340

    Expectations:
    - mask_block_cnt is (B, H, M) and mask_block_idx is (B, H, M, N).
    - Batch/head dims may be 1 for broadcast, or match the requested sizes.
    - sparse_block_size_kv must match tile_n.
    - sparse_block_size_q must be a multiple of q_stage * tile_m.
    - If sparse_block_size_q is omitted and seqlen_q/num_m_blocks is ambiguous,
      the caller must provide block_size to disambiguate. TODO will make this required in a future PR.
    """
    base_m_block = q_stage * m_block_size
    base_n_block = n_block_size
    if sparse_block_size_kv is None:
        sparse_block_size_kv = base_n_block
    if sparse_block_size_kv != base_n_block:
        raise ValueError(
            f"Block sparse tensors{context} require BLOCK_SIZE_KV={base_n_block}."
        )
    if tensors.mask_block_idx is None:
        raise ValueError(
            "mask_block_cnt and mask_block_idx must be provided for block sparsity."
        )
    num_m_blocks = tensors.mask_block_idx.shape[2]

    if sparse_block_size_q is None:
        sparse_block_size_q = get_sparse_q_block_size(tensors, seqlen_q)
        if sparse_block_size_q is None and base_m_block != 1:
            raise ValueError(
                f"Block sparse tensors{context} require explicit sparse_block_size[0] "
                f"to disambiguate block size for seqlen_q={seqlen_q} and num_m_blocks={num_m_blocks}."
            )
        if sparse_block_size_q is None:
            sparse_block_size_q = ceildiv(seqlen_q, num_m_blocks)

    if sparse_block_size_q % base_m_block != 0:
        raise ValueError(
            f"Block sparse tensors{context} have block size {sparse_block_size_q}, "
            f"which must be a multiple of {base_m_block}."

View on GitHub (pinned to 0132848349)

Solutions

1. Provide mask_block_cnt and mask_block_idx (shapes (B,H,M) and (B,H,M,N))
2. If the mask genuinely has no sparse blocks, pass all-zero/int32-empty mask tensors rather than None

Example fix

// before
tensors = BlockSparseTensorsTorch(mask_block_cnt=None, mask_block_idx=None, ...)
// after
tensors = BlockSparseTensorsTorch(mask_block_cnt=cnt, mask_block_idx=idx, ...)

assert tensors.mask_block_cnt is not None and tensors.mask_block_idx is not None

def has_mask(t): return t.mask_block_cnt is not None and t.mask_block_idx is not None

When it happens

Trigger: Constructing BlockSparseTensorsTorch with only full_block_cnt/full_block_idx (or empty) and calling normalize_block_sparse_config.

Common situations: Converting a BlockMask that only carries 'full' blocks, or a partial conversion utility that dropped the mask fields.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• v_cache must be provided
• q must be provided unless qv is provided with only_qv=True
• {name}_block_cnt and {name}_block_idx must both be provided
• spt requires dq_write_order to be provided
• LoRA batch_info must provide max_len or seg_lens.

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