xai-org/x-algorithm · error · ValueError

Block sparse tensors{context} require explicit sparse_block_

Error message

Block sparse tensors{context} require explicit sparse_block_size[0] to disambiguate block size for seqlen_q={seqlen_q} and num_m_blocks={num_m_blocks}.

What it means

When sparse_block_size_q is not given, the library tries to infer it from get_sparse_q_block_size(tensors, seqlen_q); if inference returns None and base_m_block != 1, the Q block size is ambiguous (multiple block sizes could produce the observed num_m_blocks), so an explicit sparse_block_size[0] is required.

Source

Thrown at phoenix/xrex/cutedsl/ranker_fa4/block_sparsity.py:319

    q_stage: int,
    context: str,
    sparse_block_size_q: int | None = None,
    sparse_block_size_kv: int | None = None,
) -> Tuple[Tuple[int, int, int], Tuple[int, int, int, int], int]:
    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}."
        )

    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)

View on GitHub (pinned to 24c60942c5)

Solutions

Pass sparse_block_size_q explicitly (sparse_block_size[0]) matching how the mask metadata was generated
Regenerate mask tensors with a well-defined Q block size so inference succeeds
Verify num_m_blocks = ceildiv(seqlen_q, sparse_block_size_q) for your chosen size

Example fix

# before
cfg = normalize_block_sparse_config(tensors, ..., sparse_block_size=None)

# after
q_bs = ceil(seqlen_q / tensors.mask_block_idx.shape[2])
cfg = normalize_block_sparse_config(tensors, ..., sparse_block_size=(q_bs, None))

Defensive patterns

Strategy: validation

Validate before calling

from math import ceil
num_m = tensors.mask_block_idx.shape[2]
q_bs = ceil(seqlen_q / num_m)
assert q_bs * num_m >= seqlen_q  # then pass (q_bs, None) explicitly

Prevention

Always pass sparse_block_size_q explicitly when base_m_block > 1
Store the block size used to generate masks alongside the metadata

When it happens

Trigger: Calling normalize_block_sparse_config without sparse_block_size_q while the mask tensors lack enough information to infer the Q block size and q_stage * m_block_size > 1 — e.g. seqlen_q that divides evenly under several candidate block sizes.

Common situations: Using a custom seqlen_q or packing strategy where ceildiv(seqlen_q, num_m_blocks) is not the true block size; switching from per-token (base_m_block==1) to multi-token M-blocks without updating config.

Related errors

AI-assisted analysis of xai-org/x-algorithm@24c60942c5 (2026-08-28). Data as JSON: /api/errors/298e5ace54fa7101. Report an issue: GitHub.