xai-org/x-algorithm · error · ValueError

Block sparse tensors{context} must share the same m-block di

Error message

Block sparse tensors{context} must share the same m-block dimension.

What it means

mask_block_cnt (B, H, M) and mask_block_idx (B, H, M, N) must agree on their third dimension — the number of M (query) blocks per (batch, head). A mismatch means the per-row block counts don't line up with the index rows.

Source

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

        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(
            f"Block sparse tensors{context} must have shapes (B, H, M) and (B, H, M, N)."
        )
    for dim_name, cur, tgt in (
        ("batch", mask_block_cnt.shape[0], expected_count_shape[0]),
        ("head", mask_block_cnt.shape[1], expected_count_shape[1]),
    ):
        if cur != tgt and cur != 1:
            raise ValueError(f"Block sparse tensors{context} {dim_name} dim must be {tgt} or 1.")
    for dim_name, cur, tgt in (
        ("batch", mask_block_idx.shape[0], expected_index_shape[0]),
        ("head", mask_block_idx.shape[1], expected_index_shape[1]),
    ):
        if cur != tgt and cur != 1:
            raise ValueError(f"Block sparse tensors{context} {dim_name} dim must be {tgt} or 1.")
    if mask_block_cnt.shape[2] != mask_block_idx.shape[2]:
        raise ValueError(f"Block sparse tensors{context} must share the same m-block dimension.")
    if mask_block_idx.shape[3] > expected_n_blocks:
        raise ValueError(
            f"Block sparse tensors{context} n-block dimension must be <= {expected_n_blocks}."
        )
    if expected_m_blocks != num_m_blocks:
        raise ValueError(
            f"Block sparse tensors{context} m-block dimension {num_m_blocks} does not match "
            f"sparse_block_size_q={sparse_block_size_q}. "
            f"Set BlockSparseTensorsTorch.block_size to match the BlockMask BLOCK_SIZE."
        )
    return expected_count_shape, expected_index_shape, q_subtile_factor


def get_block_sparse_expected_shapes_bwd(
    batch_size: int,
    num_head: int,
    seqlen_q: int,
    seqlen_k: int,

View on GitHub (pinned to 24c60942c5)

Solutions

1. Rebuild cnt and idx together from the same BlockMask/sparsity pattern so M always matches
2. If cropping/padding M blocks, apply the same operation to both tensors
3. Assert cnt.shape[2] == idx.shape[2] in your mask-construction code

Example fix

# before
cnt = cnt[:, :, :new_m]              # cropped
idx = idx                             # not cropped -> mismatch

# after
cnt = cnt[:, :, :new_m]
idx = idx[:, :, :new_m, :]            # keep M dims in sync
assert cnt.shape[2] == idx.shape[2]

assert tensors.mask_block_cnt.shape[2] == tensors.mask_block_idx.shape[2], \
    (tensors.mask_block_cnt.shape, tensors.mask_block_idx.shape)

When it happens

Trigger: Building cnt and idx from different sources or after independently reshaping/slicing them, so cnt.shape[2] != idx.shape[2]; e.g. truncating the M dimension of one tensor but not the other.

Common situations: Padding or cropping sequence blocks for varlen batches applied to only one of the two tensors; regenerating one tensor after a seqlen change while caching the other.

Understand the failure class

Background: Tensor shape mismatch errors ("must have shape", "expected shape ... got ..."): when tensor dimensions disagree with what an op or layer was told to expect — this error's family across 6 libraries.

Related errors

• Block sparse tensors{context} must have shapes (B, H, M) and
• Block sparse tensors{context} {dim_name} dim must be {tgt} o
• Only 1D arrays are supported for unique.
• {name}_block_cnt and {name}_block_idx must be on the same de
• {name}_block tensors must live on CUDA

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