{"record":{"id":"fda5137b1fea3141","repo":"sgl-project/sglang","slug":"kv-canary-name-must-be-1-d-got-shape-tuple-te","errorCode":null,"errorMessage":"kv-canary: {name} must be 1-D, got shape {tuple(tensor.shape)}","messagePattern":"kv-canary: (.+?) must be 1-D, got shape (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/kernels/ops/kv_canary/plan/utils.py","lineNumber":34,"sourceCode":"    when the caller passes ``None`` we substitute a one-element sentinel tensor and set ``lut_len=0``;\n    the kernel's constexpr branch guarantees no dereference happens. Dtype matches the production LUT\n    (int64) so Triton ``tl.load`` element typing stays consistent.\n    \"\"\"\n    if lut is not None:\n        return lut, int(lut.shape[0]), True\n    return torch.zeros(1, dtype=torch.int64, device=device), 0, False\n\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","sourceCodeStart":16,"sourceCodeEnd":52,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/kernels/ops/kv_canary/plan/utils.py#L16-L52","documentation":"Plan-kernel helpers enforce that indexed inputs are 1-D vectors; a 2-D tensor (or scalar/0-D) means the caller reshaped or batched the input in a way the kernel cannot interpret.","triggerScenarios":"Calling launch_plan_offsets_kernel with e.g. prefix_lens of shape [bs, 1] or [1, bs] instead of [bs]; passing a scalar where a length-1 vector is required.","commonSituations":"Inputs coming from code that adds a trailing dimension for other kernels; squeeze/unsqueeze mismatches after a refactor.","solutions":["Reshape the named tensor to 1-D: t = t.reshape(-1) or t.squeeze(-1) as appropriate","Check the error's tensor name and shape to see which dimension is spurious"],"exampleFix":"// before\nprefix_lens = prefix_lens.unsqueeze(-1)  # [bs, 1]\nlaunch_plan_offsets_kernel(..., prefix_lens=prefix_lens, ...)\n// after\nprefix_lens = prefix_lens.reshape(-1)  # [bs]\nlaunch_plan_offsets_kernel(..., prefix_lens=prefix_lens, ...)","handlingStrategy":"type-guard","validationCode":"t = t.reshape(-1)","typeGuard":"def is_1d(t: torch.Tensor) -> bool:\n    return t.ndim == 1","tryCatchPattern":null,"preventionTips":["Normalize per-request inputs with reshape(-1) before launch"],"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"}