{"record":{"id":"cbd42fdcc19a4c84","repo":"xai-org/x-algorithm","slug":"block-sparse-tensors-context-n-block-dimension-mu","errorCode":null,"errorMessage":"Block sparse tensors{context} n-block dimension must be <= {expected_n_blocks}.","messagePattern":"Block sparse tensors(.+?) n-block dimension must be <= (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"phoenix/xrex/cutedsl/ranker_fa4/block_sparsity.py","lineNumber":361,"sourceCode":"        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        )\n    return expected_count_shape, expected_index_shape, q_subtile_factor\n\n\ndef get_block_sparse_expected_shapes_bwd(\n    batch_size: int,\n    num_head: int,\n    seqlen_q: int,\n    seqlen_k: int,\n    m_block_size: int,\n    n_block_size: int,","sourceCodeStart":343,"sourceCodeEnd":379,"githubUrl":"https://github.com/xai-org/x-algorithm/blob/24c60942c5c5fdad3a6addffb4c6e6d2f228f04f/phoenix/xrex/cutedsl/ranker_fa4/block_sparsity.py#L343-L379","documentation":"The last dimension of mask_block_idx (the max number of N/KV blocks indexed per row) must not exceed expected_n_blocks, the total available KV blocks. Indices pointing past the end of the KV axis would be out of bounds in the kernel.","triggerScenarios":"Passing mask_block_idx with shape[3] > expected_n_blocks, e.g. a mask built for a longer KV sequence (larger seqlen_k or smaller sparse_block_size_kv) than the current run.","commonSituations":"Reusing a mask generated for a longer context window; changing seqlen_k or the KV block size without regenerating the mask; off-by-one in n-block computation in a custom mask builder.","solutions":["Regenerate the block mask for the current seqlen_k and sparse_block_size_kv so n-block dim <= ceil(seqlen_k / block_kv)","Clip or rebuild indices so the widest row fits within expected_n_blocks","Check that expected_n_blocks is computed with the same block size as the mask generator used"],"exampleFix":"# before\nidx = build_mask(seqlen_k=8192)   # n dim = 8192/512 = 16\ncfg = normalize_block_sparse_config(..., seqlen_k=4096)  # expects <= 8\n\n# after\nidx = build_mask(seqlen_k=4096)   # n dim = 8\ncfg = normalize_block_sparse_config(..., seqlen_k=4096)","handlingStrategy":"validation","validationCode":"import math\nexp_n = math.ceil(seqlen_k / sparse_block_kv)\nassert tensors.mask_block_idx.shape[3] <= exp_n, tensors.mask_block_idx.shape","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Regenerate masks when seqlen_k or kv block size changes","Unit-test mask width against expected n-blocks in CI"],"tags":["block-sparsity","bounds-check","sequence-length"],"backgroundTag":"index-out-of-bounds-prevention","analyzedSha":"24c60942c5c5fdad3a6addffb4c6e6d2f228f04f","analyzedAt":"2026-08-28T11:40:14.686Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}