sgl-project/sglang · error · ValueError

Block sparse tensors{context} have block size {sparse_block_

Error message

Block sparse tensors{context} have block size {sparse_block_size_q}, which must be a multiple of {base_m_block}.

What it means

Raised when the inferred or provided q sparse block size is not a multiple of the kernel's q tile size (q_stage * m_block_size). FA4 iterates q in tiles of base_m_block, so a finer-grained mask cannot be honored.

Source

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

        )
    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}."
        )

    expected_m_blocks = ceildiv(seqlen_q, sparse_block_size_q)
    expected_n_blocks = ceildiv(seqlen_k, sparse_block_size_kv)
    q_subtile_factor = sparse_block_size_q // base_m_block
    expected_count_shape = (batch_size, num_head, expected_m_blocks)
    expected_index_shape = (batch_size, num_head, expected_m_blocks, expected_n_blocks)

    mask_block_cnt = tensors.mask_block_cnt
    mask_block_idx = tensors.mask_block_idx
    if mask_block_cnt is None or mask_block_idx is None:
        raise ValueError(
            "mask_block_cnt and mask_block_idx must be provided for block sparsity."
        )
    if mask_block_cnt.ndim != 3 or mask_block_idx.ndim != 4:
        raise ValueError(

View on GitHub (pinned to 0132848349)

Solutions

1. Rebuild the mask with a q block size that is a multiple of the kernel's q tile (e.g. 128 or 256)
2. Change the kernel's q_stage/m_block_size so base_m_block divides sparse_block_size_q

Example fix

// before
BlockMask(block_size_q=64, ...)
// after
BlockMask(block_size_q=128, ...)  # multiple of kernel q tile

assert sparse_block_size_q % base_m_block == 0, 'q block size must be multiple of kernel q tile'

When it happens

Trigger: sparse_block_size_q=64 while the kernel's base_m_block=128; raises during normalize_block_sparse_config.

Common situations: Using a BlockMask built for a different kernel configuration (smaller q blocks) with the current FA4 tile size.

Related errors

• Block sparse tensors{context} require BLOCK_SIZE_KV={base_n_
• Block sparse tensors{context} m-block dimension {num_m_block
• Previous frame size does not match current delta payload
• Unsupported content type ${header.content_type}
• Error: --model-type requires a value.

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