{"record":{"id":"166f6d0120e8b808","repo":"sgl-project/sglang","slug":"tensor-name-context-clause-with-shape-tensor-s","errorCode":null,"errorMessage":"{tensor_name}{context_clause} with shape {tensor.shape} cannot be expanded to expected shape {expected_shape}.{hint_clause}","messagePattern":"(.+?)(.+?) with shape (.+?) cannot be expanded to expected shape (.+?)\\.(.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/kernels/ops/attention/flash_attn/cute/block_sparsity.py","lineNumber":225,"sourceCode":"def _expand_sparsity_tensor(\n    tensor: torch.Tensor,\n    expected_shape: Tuple[int, ...],\n    tensor_name: str,\n    context: str | None,\n    hint: str | Callable[[], str] | None,\n) -> torch.Tensor:\n    \"\"\"Check if we need to expand the tensor to expected shape, and do so if possible.\"\"\"\n    needs_expand = tensor.shape != expected_shape\n    if not needs_expand:\n        return tensor\n    can_expand = all(\n        map(lambda cur, tgt: cur == tgt or cur == 1, tensor.shape, expected_shape)\n    )\n    if not can_expand:\n        context_clause = f\" ({context})\" if context else \"\"\n        resolved_hint = hint() if callable(hint) else hint\n        hint_clause = f\" Hint: {resolved_hint}\" if resolved_hint else \"\"\n        raise ValueError(\n            f\"{tensor_name}{context_clause} with shape {tensor.shape} cannot be expanded to expected shape {expected_shape}.\"\n            f\"{hint_clause}\"\n        )\n    return tensor.expand(*expected_shape)\n\n\ndef _check_and_expand_block(\n    name: str,\n    cnt: torch.Tensor | None,\n    idx: torch.Tensor | None,\n    expected_count_shape: Tuple[int, ...],\n    expected_index_shape: Tuple[int, ...],\n    context: str | None,\n    hint: str | Callable[[], str] | None,\n) -> Tuple[torch.Tensor | None, torch.Tensor | None]:\n    if (cnt is None) != (idx is None):\n        raise ValueError(\n            f\"{name}_block_cnt and {name}_block_idx must both be provided or both be None\"","sourceCodeStart":207,"sourceCodeEnd":243,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/kernels/ops/attention/flash_attn/cute/block_sparsity.py#L207-L243","documentation":"_expand_sparsity_tensor validates that a block-sparsity metadata tensor can be broadcast (expand) to the expected shape: every dim must match or be 1. Otherwise it raises ValueError with tensor name, context, shapes, and an optional hint.","triggerScenarios":"Passing a *_block_cnt/*_block_idx tensor to normalize_block_sparse_tensors whose shape has a dim that neither equals the expected dim nor is 1 (e.g. batch of 1 when 8 heads expected, or swapped head/level dims).","commonSituations":"Configuring FlashAttention block-sparsity (e.g. MoBA/block-sparse attention) with per-request metadata that doesn't broadcast across batch or heads; wrong tensor layout from a sparsity planner.","solutions":["Fix the metadata tensor shape so each dim equals the expected dim or is 1 (broadcastable)","Expand leading dims explicitly: tensor.expand(B, H, ...) before passing","Print expected_shape from the error and reshape/permute the metadata to match"],"exampleFix":"# before\ncnt = torch.zeros(num_blocks, dtype=torch.int32, device='cuda')  # expected [B, H, ...]\n# after\ncnt = cnt.expand(B, H, *cnt.shape).contiguous()  # or build with full shape","handlingStrategy":"validation","validationCode":"def broadcastable(t, expected):\\n    return all(c == e or c == 1 for c, e in zip(t.shape, expected))\\nassert broadcastable(cnt, expected_cnt_shape) and broadcastable(idx, expected_idx_shape)","typeGuard":"def is_expandable(tensor: torch.Tensor, expected_shape: tuple) -> bool:\\n    return all(c == e or c == 1 for c, e in zip(tensor.shape, expected_shape))","tryCatchPattern":null,"preventionTips":["Log metadata shapes next to expected shapes in tests","Build metadata with full target shape rather than relying on broadcast"],"tags":["block-sparse","attention","shape-mismatch","broadcast"],"backgroundTag":"tensor-shape-mismatch","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}