{"record":{"id":"218f56e7a72f9cd4","repo":"xai-org/x-algorithm","slug":"block-sparse-tensors-context-dim-name-dim-must","errorCode":null,"errorMessage":"Block sparse tensors{context} {dim_name} dim must be {tgt} or 1.","messagePattern":"Block sparse tensors(.+?) (.+?) dim must be (.+?) or 1\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"phoenix/xrex/cutedsl/ranker_fa4/block_sparsity.py","lineNumber":351,"sourceCode":"    expected_n_blocks = ceildiv(seqlen_k, sparse_block_size_kv)\n    q_subtile_factor = sparse_block_size_q // base_m_block\n    expected_count_shape = (batch_size, num_head, expected_m_blocks)\n    expected_index_shape = (batch_size, num_head, expected_m_blocks, expected_n_blocks)\n\n    mask_block_cnt = tensors.mask_block_cnt\n    mask_block_idx = tensors.mask_block_idx\n    if mask_block_cnt is None or mask_block_idx is None:\n        raise ValueError(\"mask_block_cnt and mask_block_idx must be provided for block sparsity.\")\n    if mask_block_cnt.ndim != 3 or mask_block_idx.ndim != 4:\n        raise ValueError(\n            f\"Block sparse tensors{context} must have shapes (B, H, M) and (B, H, M, N).\"\n        )\n    for dim_name, cur, tgt in (\n        (\"batch\", mask_block_cnt.shape[0], expected_count_shape[0]),\n        (\"head\", mask_block_cnt.shape[1], expected_count_shape[1]),\n    ):\n        if cur != tgt and cur != 1:\n            raise ValueError(f\"Block sparse tensors{context} {dim_name} dim must be {tgt} or 1.\")\n    for dim_name, cur, tgt in (\n        (\"batch\", mask_block_idx.shape[0], expected_index_shape[0]),\n        (\"head\", mask_block_idx.shape[1], expected_index_shape[1]),\n    ):\n        if cur != tgt and cur != 1:\n            raise ValueError(f\"Block sparse tensors{context} {dim_name} dim must be {tgt} or 1.\")\n    if mask_block_cnt.shape[2] != mask_block_idx.shape[2]:\n        raise ValueError(f\"Block sparse tensors{context} must share the same m-block dimension.\")\n    if mask_block_idx.shape[3] > expected_n_blocks:\n        raise ValueError(\n            f\"Block sparse tensors{context} n-block dimension must be <= {expected_n_blocks}.\"\n        )\n    if expected_m_blocks != num_m_blocks:\n        raise ValueError(\n            f\"Block sparse tensors{context} m-block dimension {num_m_blocks} does not match \"\n            f\"sparse_block_size_q={sparse_block_size_q}. \"\n            f\"Set BlockSparseTensorsTorch.block_size to match the BlockMask BLOCK_SIZE.\"\n        )","sourceCodeStart":333,"sourceCodeEnd":369,"githubUrl":"https://github.com/xai-org/x-algorithm/blob/24c60942c5c5fdad3a6addffb4c6e6d2f228f04f/phoenix/xrex/cutedsl/ranker_fa4/block_sparsity.py#L333-L369","documentation":"Validates that mask_block_cnt's batch and head dims match the expected count shape (or are 1 for broadcasting). The kernel only broadcasts size-1 dims; any other mismatch between the tensor's B/H and the model's batch/head count fails immediately.","triggerScenarios":"normalize_block_sparse_config with mask_block_cnt whose shape[0] != batch (and != 1) or shape[1] != num_head (and != 1), e.g. running batch=4 inference with a mask built for batch=1 but reshaped to 2, or a per-layer head count differing from the mask's head dim.","commonSituations":"Reusing a cached/precomputed block mask across batch sizes or model variants (different num_attention_heads); H100 vs Blackwell configs with different head counts; forgetting that only literal 1 broadcasts.","solutions":["Set the mismatched dim to 1 so it broadcasts, or rebuild the mask with the correct batch/head dimensions","Verify the num_head/batch arguments passed to normalize_block_sparse_config match the tensors' shapes","If the mask is shared across layers with different head counts, expand it explicitly to the max head count"],"exampleFix":"// before\ncnt = torch.load('mask.pt')           # (2, 32, M) but batch=4\ncfg = normalize_block_sparse_config(tensors, batch_size=4, num_head=32, ...)\n\n// after\ncnt = torch.load('mask.pt')\nif cnt.shape[0] not in (4, 1):\n    cnt = cnt[:1].expand(4, -1, -1).contiguous()   # (4, 32, M)\ncfg = normalize_block_sparse_config(tensors, batch_size=4, num_head=32, ...)","handlingStrategy":"validation","validationCode":"def check_bh(t, dim, expected, allowed=(1,)):\n    s = t.shape[dim]\n    assert s == expected or s in allowed, f'dim {dim}: {s} != {expected}'\ncheck_bh(tensors.mask_block_cnt, 0, batch); check_bh(tensors.mask_block_cnt, 1, num_head)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Derive mask B/H dims from the same variables used for the model config","Use size-1 dims for broadcastable masks"],"tags":["block-sparsity","broadcasting","shape-validation"],"backgroundTag":"tensor-shape-mismatch","analyzedSha":"24c60942c5c5fdad3a6addffb4c6e6d2f228f04f","analyzedAt":"2026-08-28T11:40:14.686Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}