{"record":{"id":"16bb7623508c36a5","repo":"sgl-project/sglang","slug":"kv-canary-name-must-be-2-d-got-shape-tuple-te","errorCode":null,"errorMessage":"kv-canary: {name} must be 2-D, got shape {tuple(tensor.shape)}","messagePattern":"kv-canary: (.+?) must be 2-D, got shape (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/kernels/ops/kv_canary/plan/utils.py","lineNumber":41,"sourceCode":"\n\ndef _require_dtype(tensor: torch.Tensor, name: str, dtype: torch.dtype) -> None:\n    if tensor.dtype != dtype:\n        raise ValueError(\n            f\"kv-canary: {name} must have dtype {dtype}, got {tensor.dtype}\"\n        )\n\n\ndef _require_1d(tensor: torch.Tensor, name: str) -> None:\n    if tensor.ndim != 1:\n        raise ValueError(\n            f\"kv-canary: {name} must be 1-D, got shape {tuple(tensor.shape)}\"\n        )\n\n\ndef _require_2d(tensor: torch.Tensor, name: str) -> None:\n    if tensor.ndim != 2:\n        raise ValueError(\n            f\"kv-canary: {name} must be 2-D, got shape {tuple(tensor.shape)}\"\n        )\n\n\ndef _require_len(tensor: torch.Tensor, name: str, expected: int) -> None:\n    _require_1d(tensor=tensor, name=name)\n    actual = int(tensor.shape[0])\n    if actual != expected:\n        raise ValueError(f\"kv-canary: {name} length must be {expected}, got {actual}\")\n\n\ndef _require_min_len(tensor: torch.Tensor, name: str, minimum: int) -> None:\n    _require_1d(tensor=tensor, name=name)\n    actual = int(tensor.shape[0])\n    if actual < minimum:\n        raise ValueError(f\"kv-canary: {name} length must be >= {minimum}, got {actual}\")\n\n","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/kernels/ops/kv_canary/plan/utils.py#L23-L59","documentation":"The req_to_token mapping must be a 2-D [max_reqs, max_context] tensor; the offsets kernel validates ndim==2 before computing row addresses from stride(0).","triggerScenarios":"Calling launch_plan_offsets_kernel with req_to_token that is 1-D, 3-D, or a flattened view instead of a proper 2-D mapping.","commonSituations":"The mapping tensor being flattened for transport and not reshaped back; passing a per-shard slice with the wrong rank.","solutions":["Reshape req_to_token to 2-D: req_to_token = req_to_token.reshape(max_reqs, max_context_len)","Verify the tensor comes from the KV cache manager's req_to_token pool unchanged"],"exampleFix":"// before\nreq_to_token = req_to_token.reshape(-1)\n// after\nreq_to_token = req_to_token.reshape(max_reqs, max_context_len)","handlingStrategy":"type-guard","validationCode":"req_to_token = req_to_token.reshape(max_reqs, max_context_len)","typeGuard":"def is_2d(t: torch.Tensor) -> bool:\n    return t.ndim == 2","tryCatchPattern":null,"preventionTips":["Pass req_to_token straight from the KV pool without re-shaping"],"tags":["kv-canary","shape","validation"],"backgroundTag":"tensor-shape-mismatch","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}