{"record":{"id":"57cd518c18be2d8a","repo":"sgl-project/sglang","slug":"block-sparse-tensors-context-dim-name-dim-must","errorCode":null,"errorMessage":"Block sparse tensors{context} {dim_name} dim must be {tgt} or 1.","messagePattern":"Block sparse tensors(.+?) (.+?) dim must be (.+?) or 1\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/kernels/ops/attention/flash_attn/cute/block_sparsity.py","lineNumber":374,"sourceCode":"        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\n    expected_m_blocks = ceildiv(seqlen_q, sparse_block_size_q)\n    expected_n_blocks = ceildiv(seqlen_k, sparse_block_size_kv)\n    q_subtile_factor = sparse_block_size_q // base_m_block\n    expected_count_shape = (batch_size, num_head, expected_m_blocks)\n    expected_index_shape = (batch_size, num_head, expected_m_blocks, expected_n_blocks)\n\n    mask_block_cnt = tensors.mask_block_cnt\n    mask_block_idx = tensors.mask_block_idx\n    if mask_block_cnt is None or mask_block_idx is None:\n        raise ValueError(\n            \"mask_block_cnt and mask_block_idx must be provided for block sparsity.\"\n        )\n    if mask_block_cnt.ndim != 3 or mask_block_idx.ndim != 4:\n        raise ValueError(\n            f\"Block sparse tensors{context} must have shapes (B, H, M) and (B, H, M, N).\"\n        )\n    for dim_name, cur, tgt in (\n        (\"batch\", mask_block_cnt.shape[0], expected_count_shape[0]),\n        (\"head\", mask_block_cnt.shape[1], expected_count_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    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            )","sourceCodeStart":356,"sourceCodeEnd":392,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/kernels/ops/attention/flash_attn/cute/block_sparsity.py#L356-L392","documentation":"Raised when mask_block_cnt's batch or head dimension is neither the expected value nor 1 (broadcastable). Dimensions of size 1 are expanded; any other mismatch is rejected.","triggerScenarios":"mask_block_cnt.shape[1]=4 while the attention call has num_head=8 (and not 1), during normalize_block_sparse_config.","commonSituations":"Model change (different num_heads) reusing an old mask, or GQA conversion that forgot to align the head dim of the count tensor.","solutions":["Set the head dim to num_head or squeeze to 1 for a head-shared mask: cnt = cnt[:, :1] / build with H=1","Regenerate the mask for the current model's head count"],"exampleFix":"// before\ncnt = torch.zeros((B, 4, M), ...)  # num_head=8\n// after\ncnt = torch.zeros((B, 1, M), ...)  # broadcast over heads","handlingStrategy":"validation","validationCode":"for name, cur, tgt in (('b', cnt.shape[0], B), ('h', cnt.shape[1], H)):\n    assert cur in (tgt, 1), f'{name} dim {cur} must be {tgt} or 1'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use head dim 1 for head-shared masks","Regenerate masks when num_heads changes"],"tags":["block-sparse","shape-mismatch","broadcasting"],"backgroundTag":"tensor-shape-mismatch","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}