{"record":{"id":"e669d3a6052491b2","repo":"xai-org/x-algorithm","slug":"block-sparse-tensors-context-require-block-size-k","errorCode":null,"errorMessage":"Block sparse tensors{context} require BLOCK_SIZE_KV={base_n_block}.","messagePattern":"Block sparse tensors(.+?) require BLOCK_SIZE_KV=(.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"phoenix/xrex/cutedsl/ranker_fa4/block_sparsity.py","lineNumber":311,"sourceCode":"    tensors: BlockSparseTensorsTorch,\n    *,\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,\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}.\"","sourceCodeStart":293,"sourceCodeEnd":329,"githubUrl":"https://github.com/xai-org/x-algorithm/blob/24c60942c5c5fdad3a6addffb4c6e6d2f228f04f/phoenix/xrex/cutedsl/ranker_fa4/block_sparsity.py#L293-L329","documentation":"infer_block_sparse_expected_shapes (via normalize_block_sparse_config) enforces that the KV block size of the sparse metadata equals the kernel's BLOCK_SIZE_KV (n_block_size). If the user supplies sparse_block_size_kv different from the kernel's n_block_size, the block indices cannot be mapped to kernel tiles and the call is rejected.","triggerScenarios":"Calling the config API with sparse_block_size_kv set to a value != n_block_size (e.g. 128 vs kernel tile 64), or constructing mask tensors with a different KV granularity than the attention kernel was configured with.","commonSituations":"Changing the kernel tile size (n_block_size) without regenerating the block-sparse metadata; reusing sparse schedules computed for a different model/config; copying example code that assumed a different BLOCK_SIZE_KV.","solutions":["Set sparse_block_size_kv=None so it defaults to base_n_block (n_block_size)","Regenerate mask_block_cnt/idx with block size equal to n_block_size","Align the kernel config so n_block_size matches the metadata's KV block size"],"exampleFix":"# before\ncfg = normalize_block_sparse_config(..., sparse_block_size=(64, 128))  # 128 != n_block_size\n\n# after\ncfg = normalize_block_sparse_config(..., sparse_block_size=(64, None))  # kv defaults to n_block_size","handlingStrategy":"validation","validationCode":"assert sparse_block_size_kv in (None, n_block_size), f\"kv block size must equal BLOCK_SIZE_KV={n_block_size}\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Leave sparse_block_size_kv as None to inherit the kernel's n_block_size","Regenerate sparse metadata whenever kernel tile sizes change"],"tags":["block-sparsity","config-validation","block-size"],"backgroundTag":"block-sparsity-config-mismatch","analyzedSha":"24c60942c5c5fdad3a6addffb4c6e6d2f228f04f","analyzedAt":"2026-08-28T11:40:14.686Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}