{"record":{"id":"46d8cadf5eb24968","repo":"sgl-project/sglang","slug":"rope-pool-fused-expects-positions-slots-to-be-1-d","errorCode":null,"errorMessage":"rope_pool_fused expects positions/slots to be 1-D","messagePattern":"rope_pool_fused expects positions/slots to be 1-D","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/kernels/aot/python/sgl_kernel/metal.py","lineNumber":66,"sourceCode":"    \"\"\"Apply NeoX RoPE to Q/K and scatter K/V into the MLX KV pool.\n\n    Args:\n        q: Query tensor with shape `[num_tokens, num_qo_heads, head_dim]`.\n        k: Key tensor with shape `[num_tokens, num_kv_heads, head_dim]`.\n        v: Value tensor with shape `[num_tokens, num_kv_heads, head_dim]`.\n        positions: int32 positions with shape `[num_tokens]`.\n        slots: int32 KV-pool slots with shape `[num_tokens]`; values `< 0`\n            skip the pool write for that token.\n        k_pool: Existing K pool with shape `[pool_size, num_kv_heads, head_dim]`.\n        v_pool: Existing V pool with shape `[pool_size, num_kv_heads, head_dim]`.\n\n    Returns:\n        `(q_rot, k_rot, k_pool_new, v_pool_new)`.\n    \"\"\"\n    if q.ndim != 3 or k.ndim != 3 or v.ndim != 3:\n        raise ValueError(\"rope_pool_fused expects q/k/v to be 3-D\")\n    if positions.ndim != 1 or slots.ndim != 1:\n        raise ValueError(\"rope_pool_fused expects positions/slots to be 1-D\")\n    if k_pool.ndim != 3 or v_pool.ndim != 3:\n        raise ValueError(\"rope_pool_fused expects pool tensors to be 3-D\")\n    q_shape = tuple(q.shape)\n    k_shape = tuple(k.shape)\n    v_shape = tuple(v.shape)\n    positions_shape = tuple(positions.shape)\n    slots_shape = tuple(slots.shape)\n    k_pool_shape = tuple(k_pool.shape)\n    v_pool_shape = tuple(v_pool.shape)\n\n    if q_shape != (q_shape[0], num_qo_heads, head_dim):\n        raise ValueError(\n            \"q shape must be [num_tokens, num_qo_heads, head_dim], \" f\"got {q.shape}\"\n        )\n    if k_shape != (q_shape[0], num_kv_heads, head_dim):\n        raise ValueError(\n            \"k shape must be [num_tokens, num_kv_heads, head_dim], \" f\"got {k.shape}\"\n        )","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/kernels/aot/python/sgl_kernel/metal.py#L48-L84","documentation":"rope_pool_fused requires the per-token positions and pool slot indices to be 1-D tensors of length num_tokens. This error fires when either positions or slots has more than one dimension (or is scalars/2-D), because the kernel iterates tokens with a single flat index array.","triggerScenarios":"Calling rope_pool_fused with positions or slots shaped [batch, seq] instead of [num_tokens], or passing scalar/0-D tensors for a single token instead of 1-D length-1 tensors.","commonSituations":"Porting code from attention backends that take batched position tensors; forgetting to flatten positions generated per batch; passing Python ints or 0-D tensors instead of torch tensors of shape [1].","solutions":["Flatten positions/slots to 1-D: positions = positions.reshape(-1); slots = slots.reshape(-1)","If using scalars, wrap them: torch.tensor([pos], dtype=torch.int64)","Verify positions.ndim == 1 and slots.ndim == 1 before the call"],"exampleFix":"# before\nmetal.rope_pool_fused(q, k, v, positions, slots, ...)  # positions is [B, S]\n\n# after\npositions = positions.reshape(-1)\nslots = slots.reshape(-1)\nmetal.rope_pool_fused(q, k, v, positions, slots, ...)","handlingStrategy":"validation","validationCode":"assert positions.ndim == 1 and slots.ndim == 1, (positions.shape, slots.shape)","typeGuard":"def flat_index(t) -> bool:\n    import torch\n    return isinstance(t, torch.Tensor) and t.ndim == 1","tryCatchPattern":null,"preventionTips":["Always reshape(-1) positions/slots derived from batched sources","Wrap scalar positions in torch.tensor([x])"],"tags":["shape-validation","rope","metal","positions","sgl-kernel"],"backgroundTag":"tensor-shape-mismatch","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}