{"record":{"id":"963781c441169027","repo":"sgl-project/sglang","slug":"block-sparse-tensors-context-m-block-dimension-n","errorCode":null,"errorMessage":"Block sparse tensors{context} m-block dimension {num_m_blocks} does not match sparse_block_size_q={sparse_block_size_q}. Set BlockSparseTensorsTorch.block_size to match the BlockMask BLOCK_SIZE.","messagePattern":"Block sparse tensors(.+?) m-block dimension (.+?) does not match sparse_block_size_q=(.+?)\\. Set BlockSparseTensorsTorch\\.block_size to match the BlockMask BLOCK_SIZE\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/kernels/ops/attention/flash_attn/cute/block_sparsity.py","lineNumber":400,"sourceCode":"            raise ValueError(\n                f\"Block sparse tensors{context} {dim_name} dim must be {tgt} or 1.\"\n            )\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(\n                f\"Block sparse tensors{context} {dim_name} dim must be {tgt} or 1.\"\n            )\n    if mask_block_cnt.shape[2] != mask_block_idx.shape[2]:\n        raise ValueError(\n            f\"Block sparse tensors{context} must share the same m-block dimension.\"\n        )\n    # [Note] Allow Compact block sparse indices: FA4 only accesses indices 0..cnt-1\n    # per query tile, so idx.shape[3] can be <= expected_n_blocks.\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":382,"sourceCodeEnd":418,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/kernels/ops/attention/flash_attn/cute/block_sparsity.py#L382-L418","documentation":"Raised when the m-block dimension of the mask does not match the number of q blocks implied by sparse_block_size_q (expected_m_blocks = ceildiv(seqlen_q, sparse_block_size_q)). Usually means the BlockMask was built with a different q block size than recorded/requested.","triggerScenarios":"num_m_blocks=64 from the mask but ceildiv(seqlen_q, sparse_block_size_q)=32, during normalize_block_sparse_config.","commonSituations":"BlockSparseTensorsTorch.block_size not set (or stale) after converting a BlockMask, so sparse_block_size_q defaults incorrectly; or seqlen_q changed between mask build and call.","solutions":["Set BlockSparseTensorsTorch.block_size to the BlockMask's BLOCK_SIZE so sparse_block_size_q matches the mask layout","Rebuild the mask with q block size consistent with the current seqlen_q","Recheck that seqlen_q (e.g. including spec-decode extra tokens) matches mask construction"],"exampleFix":"// before\ntensors = BlockSparseTensorsTorch(cnt, idx)  # block_size unset\n// after\ntensors = BlockSparseTensorsTorch(cnt, idx, block_size=(128, 128))  # match BlockMask","handlingStrategy":"validation","validationCode":"expected_m = (seqlen_q + sparse_block_size_q - 1) // sparse_block_size_q\nassert mask_block_idx.shape[2] == expected_m","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set BlockSparseTensorsTorch.block_size to the BlockMask BLOCK_SIZE","Ensure seqlen_q at call time matches mask construction"],"tags":["block-sparse","block-size","shape-mismatch"],"backgroundTag":"block-size-misaligned","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}