sgl-project/sglang · error · ValueError

mask_block_cnt and mask_block_idx must be provided for…

Error message

mask_block_cnt and mask_block_idx must be provided for block sparsity.

What it means

Raised when block sparsity is requested (e.g. via a sheared/sparse mask config) but the mask_block_cnt/mask_block_idx metadata tensors were not provided. Block-sparse execution requires both tensors to describe the sparse block layout.

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 argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• --disagg-server-addr is required for --disagg-role
• Either num_inference_steps, sigmas, or timesteps must be…
• Invalid attention metadata values.Sparsity should be in
• items must be provided
• kv-canary: launch_canary_plan_kernels_torch_reference…

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

Appendix: 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)