{"record":{"id":"5c2beadccc996f35","repo":"xai-org/x-algorithm","slug":"mask-block-cnt-and-mask-block-idx-must-be-provided","errorCode":null,"errorMessage":"mask_block_cnt and mask_block_idx must be provided for block sparsity.","messagePattern":"mask_block_cnt and mask_block_idx must be provided for block sparsity\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"phoenix/xrex/cutedsl/ranker_fa4/block_sparsity.py","lineNumber":313,"sourceCode":"    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,\n    q_stage: int,\n    context: str,\n    sparse_block_size_q: int | None = None,\n    sparse_block_size_kv: int | None = None,\n) -> Tuple[Tuple[int, int, int], Tuple[int, int, int, int], int]:\n    base_m_block = q_stage * m_block_size\n    base_n_block = n_block_size\n    if sparse_block_size_kv is None:\n        sparse_block_size_kv = base_n_block\n    if sparse_block_size_kv != base_n_block:\n        raise ValueError(f\"Block sparse tensors{context} require BLOCK_SIZE_KV={base_n_block}.\")\n    if tensors.mask_block_idx is None:\n        raise ValueError(\"mask_block_cnt and mask_block_idx must be provided for block sparsity.\")\n    num_m_blocks = tensors.mask_block_idx.shape[2]\n\n    if sparse_block_size_q is None:\n        sparse_block_size_q = get_sparse_q_block_size(tensors, seqlen_q)\n        if sparse_block_size_q is None and base_m_block != 1:\n            raise ValueError(\n                f\"Block sparse tensors{context} require explicit sparse_block_size[0] \"\n                f\"to disambiguate block size for seqlen_q={seqlen_q} and num_m_blocks={num_m_blocks}.\"\n            )\n        if sparse_block_size_q is None:\n            sparse_block_size_q = ceildiv(seqlen_q, num_m_blocks)\n\n    if sparse_block_size_q % base_m_block != 0:\n        raise ValueError(\n            f\"Block sparse tensors{context} have block size {sparse_block_size_q}, \"\n            f\"which must be a multiple of {base_m_block}.\"\n        )\n","sourceCodeStart":295,"sourceCodeEnd":331,"githubUrl":"https://github.com/xai-org/x-algorithm/blob/24c60942c5c5fdad3a6addffb4c6e6d2f228f04f/phoenix/xrex/cutedsl/ranker_fa4/block_sparsity.py#L295-L331","documentation":"infer_block_sparse_expected_shapes requires the mask_block_idx tensor to be present when block sparsity is enabled; None means the sparsity pattern itself is missing, so expected shapes cannot be inferred. This instance fires early, before num_m_blocks is read from mask_block_idx.shape[2].","triggerScenarios":"Enabling block sparsity (passing mask_block_cnt or a sparse config) but leaving tensors.mask_block_idx as None; constructing the sparse-tensor container with only one of the two mask tensors.","commonSituations":"Partially initialized dataclasses/containers where the idx field was never populated; conditionally loading only counts; forgetting to attach the precomputed index tensor when wiring up the ranker inputs.","solutions":["Provide both mask_block_cnt and mask_block_idx tensors","Check for None fields on the container before calling the API","Disable block sparsity entirely if it was enabled by mistake"],"exampleFix":"# before\ntensors = BlockSparseTensors(mask_block_cnt=cnt, mask_block_idx=None)\n\n# after\ntensors = BlockSparseTensors(mask_block_cnt=cnt, mask_block_idx=idx)","handlingStrategy":"type-guard","validationCode":"assert tensors.mask_block_cnt is not None and tensors.mask_block_idx is not None","typeGuard":"def has_block_sparsity_pair(t) -> bool:\n    return t.mask_block_cnt is not None and t.mask_block_idx is not None","tryCatchPattern":null,"preventionTips":["Make both mask fields required (no defaults) in your wrapper dataclass","Log when sparsity is enabled with incomplete metadata"],"tags":["block-sparsity","missing-argument","validation"],"backgroundTag":"missing-required-tensor","analyzedSha":"24c60942c5c5fdad3a6addffb4c6e6d2f228f04f","analyzedAt":"2026-08-28T11:40:14.686Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}