{"record":{"id":"c358f3e1e16eb52f","repo":"xai-org/x-algorithm","slug":"block-sparse-arrays-cover-bs-num-blocks-m-tiles","errorCode":null,"errorMessage":"block-sparse arrays cover {bs_num_blocks} m-tiles but the kernel iterates {(seq_len + m_block - 1) // m_block} (seq_len={seq_len})","messagePattern":"block-sparse arrays cover (.+?) m-tiles but the kernel iterates (.+?) \\(seq_len=(.+?)\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"critical","filePath":"phoenix/xrex/cutedsl/ranker_attention_fa4.py","lineNumber":100,"sourceCode":"    from xrex.cutedsl.ranker_fa4.flash_bwd_postprocess import FlashAttentionBackwardPostprocess\n    from xrex.cutedsl.ranker_fa4.flash_bwd_sm100 import FlashAttentionBackwardSm100\n    from xrex.cutedsl.ranker_fa4.flash_fwd_sm100 import FlashAttentionForwardSm100\n\n    batch_size, seq_len, num_q_heads, head_dim = q.shape\n    num_kv_heads = k.shape[2]\n    qhead_per_kvhead = num_q_heads // num_kv_heads\n    m_block = 128\n    n_block = 128\n    hdr = ((head_dim + 31) // 32) * 32\n    sr_q = ((seq_len + m_block - 1) // m_block) * m_block\n    sr_k = ((seq_len + n_block - 1) // n_block) * n_block\n    dKV_postprocess = True\n\n    fwd_bs, bwd_bs = block_sparse_layout\n    bs_num_blocks = int(fwd_bs[3].shape[-2])\n    bs_max_hist_blocks = int(fwd_bs[3].shape[-1])\n    if bs_num_blocks != (seq_len + m_block - 1) // m_block:\n        raise ValueError(\n            f\"block-sparse arrays cover {bs_num_blocks} m-tiles but the kernel \"\n            f\"iterates {(seq_len + m_block - 1) // m_block} (seq_len={seq_len})\"\n        )\n    use_pack_gqa = qhead_per_kvhead > 1 and (m_block % qhead_per_kvhead == 0)\n\n    cache_key = (\n        head_dim,\n        num_q_heads,\n        num_kv_heads,\n        batch_size,\n        seq_len,\n        bs_num_blocks,\n        bs_max_hist_blocks,\n        use_pack_gqa,\n    )\n\n    if cache_key not in _FA4_KERNEL_CACHE:\n        fa_fwd = FlashAttentionForwardSm100(","sourceCodeStart":82,"sourceCodeEnd":118,"githubUrl":"https://github.com/xai-org/x-algorithm/blob/24c60942c5c5fdad3a6addffb4c6e6d2f228f04f/phoenix/xrex/cutedsl/ranker_attention_fa4.py#L82-L118","documentation":"ranker_attention_fa4 derives the number of m-tiles it iterates from seq_len and m_block as ceil(seq_len / m_block), and requires the block-sparse layout's arrays (fwd_bs[3]) to cover exactly that many tiles. If the layout was built for a different sequence length or tile size, attention would read out-of-bounds or skip tiles, so it raises immediately.","triggerScenarios":"Calling ranker_attention_fa4 (usually via sharded_mha) with a block_sparse_layout built with a different seq_len or m_block than the one passed to the kernel; mismatch between padded/unpadded sequence lengths.","commonSituations":"Changing seq_len (e.g. different batch padding or packing) without rebuilding build_block_sparse_layout; altering m_block/block size config in one place but not the other; caching layouts across configs.","solutions":["Rebuild the block-sparse layout with the same seq_len and m_block used for the kernel call","Align padding: ensure seq_len passed to the kernel equals the seq_len used to construct fwd_bs","If layouts are cached, key the cache on (seq_len, m_block) so stale layouts are not reused"],"exampleFix":"// before\nlayout = build_block_sparse_layout(seq_len=1024, ...)\nout = ranker_attention_fa4(..., seq_len=2048, m_block=128, block_sparse_layout=layout)\n// after\nlayout = build_block_sparse_layout(seq_len=2048, ...)\nout = ranker_attention_fa4(..., seq_len=2048, m_block=128, block_sparse_layout=layout)","handlingStrategy":"validation","validationCode":"bs_num_blocks = int(fwd_bs[3].shape[-2])\nexpected = (seq_len + m_block - 1) // m_block\nassert bs_num_blocks == expected, f\"stale layout: {bs_num_blocks} vs {expected}\"","typeGuard":null,"tryCatchPattern":"try:\n    out = ranker_attention_fa4(...)\nexcept ValueError as e:\n    if \"m-tiles\" in str(e):\n        layout = build_block_sparse_layout(seq_len=seq_len, m_block=m_block, ...)\n        out = ranker_attention_fa4(...)\n    else:\n        raise","preventionTips":["Always construct the layout in the same function that owns seq_len and m_block","Cache layouts keyed on (seq_len, m_block, config hash)","Add CI tests that sweep seq_len values through sharded_mha"],"tags":["cuda","cutedsl","flash-attention","block-sparse","shape-mismatch"],"backgroundTag":"layout-shape-mismatch","analyzedSha":"24c60942c5c5fdad3a6addffb4c6e6d2f228f04f","analyzedAt":"2026-08-28T11:40:14.686Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}