{"record":{"id":"08e2ecbc276a081e","repo":"xai-org/x-algorithm","slug":"varlen-block-sparsity-requires-sparse-block-size-0","errorCode":null,"errorMessage":"Varlen block sparsity requires sparse_block_size[0]={base_m_block} (= q_stage * tile_m); got {sparse_block_size_q}.","messagePattern":"Varlen block sparsity requires sparse_block_size\\[0\\]=(.+?) \\(= q_stage \\* tile_m\\); got (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"phoenix/xrex/cutedsl/ranker_fa4/block_sparsity.py","lineNumber":563,"sourceCode":"    num_head: int,\n    seqlen_q: int,\n    seqlen_k: int,\n    block_size: tuple[int, int],\n    q_stage: int,\n) -> tuple[BlockSparseTensorsTorch, Tuple[Tuple[bool, ...], ...] | None, int]:\n    m_block_size, n_block_size = block_size\n    if tensors.block_size is None:\n        sparse_block_size_q, sparse_block_size_kv = None, n_block_size\n    else:\n        sparse_block_size_q, sparse_block_size_kv = tensors.block_size\n    if sparse_block_size_kv != n_block_size:\n        raise ValueError(\n            f\"Block sparsity requires sparse_block_size[1]={n_block_size} to match tile_n.\"\n        )\n    if tensors.cu_total_m_blocks is not None:\n        base_m_block = q_stage * m_block_size\n        if sparse_block_size_q is not None and sparse_block_size_q != base_m_block:\n            raise ValueError(\n                f\"Varlen block sparsity requires sparse_block_size[0]={base_m_block} \"\n                f\"(= q_stage * tile_m); got {sparse_block_size_q}.\"\n            )\n        total_m_blocks = tensors.mask_block_cnt.shape[-1]\n        total_n_blocks = tensors.mask_block_idx.shape[-1]\n        expected_count_shape = (num_head, total_m_blocks)\n        expected_index_shape = (num_head, total_n_blocks)\n        q_subtile_factor = 1\n    else:\n        expected_count_shape, expected_index_shape, q_subtile_factor = (\n            infer_block_sparse_expected_shapes(\n                tensors,\n                batch_size=batch_size,\n                num_head=num_head,\n                seqlen_q=seqlen_q,\n                seqlen_k=seqlen_k,\n                m_block_size=m_block_size,\n                n_block_size=n_block_size,","sourceCodeStart":545,"sourceCodeEnd":581,"githubUrl":"https://github.com/xai-org/x-algorithm/blob/24c60942c5c5fdad3a6addffb4c6e6d2f228f04f/phoenix/xrex/cutedsl/ranker_fa4/block_sparsity.py#L545-L581","documentation":"For varlen inputs (cu_total_m_blocks provided), the query-side sparse block size must be exactly q_stage * m_block_size (tile_m scaled by the query stage factor). An explicit sparse_block_size_q differing from that value is rejected.","triggerScenarios":"Varlen forward run with tensors.cu_total_m_blocks set and tensors.block_size[0] set to a value other than q_stage * tile_m; e.g. block_size=(128, 128) when q_stage=2 and tile_m=64 (expected 128... mismatches when using 64).","commonSituations":"Using a fixed block-size mask for varlen training; upgrading the kernel where q_stage changed; mask built for packed sequences with a different m-block granularity.","solutions":["Set block_size[0] to q_stage * tile_m, or clear tensors.block_size to None so the correct default is used","Rebuild the varlen mask with the kernel's current q_stage and tile_m","Verify cu_total_m_blocks, seqlen_q and the mask M-block count are mutually consistent"],"exampleFix":"# before\ntensors = BlockSparseTensorsTorch(..., block_size=(64, 128),\n                                  cu_total_m_blocks=cu)     # q_stage=2, tile_m=64\n\n# after\ntensors = BlockSparseTensorsTorch(..., block_size=(128, 128),   # 2*64\n                                  cu_total_m_blocks=cu)\n# or block_size=None","handlingStrategy":"validation","validationCode":"expected_q = q_stage * m_block_size\nassert tensors.block_size is None or tensors.block_size[0] == expected_q, \\\n    (tensors.block_size, expected_q)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["For varlen, rebuild masks whenever q_stage/tile_m changes","Default block_size to None for varlen runs"],"tags":["block-sparsity","varlen","block-size"],"backgroundTag":"configuration-mismatch","analyzedSha":"24c60942c5c5fdad3a6addffb4c6e6d2f228f04f","analyzedAt":"2026-08-28T11:40:14.686Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}