{"record":{"id":"a304ec59a2bba9c3","repo":"sgl-project/sglang","slug":"kv-canary-realkvsource-tensor-must-be-at-least-2","errorCode":null,"errorMessage":"kv-canary: RealKvSource.tensor must be at least 2-D, got shape {tuple(self.tensor.shape)}","messagePattern":"kv-canary: RealKvSource\\.tensor must be at least 2-D, got shape (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/kernels/ops/kv_canary/verify.py","lineNumber":113,"sourceCode":"            raise ValueError(\n                f\"kv-canary: RealKvSource.page_size must be >= 1, got {self.page_size}\"\n            )\n        if self.num_bytes_per_token <= 0 or self.num_bytes_per_token % 16 != 0:\n            raise ValueError(\n                f\"kv-canary: RealKvSource.num_bytes_per_token must be a positive multiple of 16, \"\n                f\"got {self.num_bytes_per_token}\"\n            )\n        if (\n            self.read_bytes <= 0\n            or self.read_bytes > self.num_bytes_per_token\n            or self.read_bytes % 16 != 0\n        ):\n            raise ValueError(\n                f\"kv-canary: RealKvSource.read_bytes must be a positive multiple of 16 in \"\n                f\"(0, num_bytes_per_token={self.num_bytes_per_token}], got {self.read_bytes}\"\n            )\n        if self.tensor.ndim < 2:\n            raise ValueError(\n                f\"kv-canary: RealKvSource.tensor must be at least 2-D, got shape {tuple(self.tensor.shape)}\"\n            )\n        row_stride_bytes = int(self.tensor.shape[1]) * self.tensor.element_size()\n        if row_stride_bytes % 16 != 0:\n            raise ValueError(\n                f\"kv-canary: RealKvSource.tensor dim-1 byte width must be a multiple of 16, \"\n                f\"got {row_stride_bytes} bytes (shape={tuple(self.tensor.shape)}, \"\n                f\"dtype={self.tensor.dtype})\"\n            )\n\n\n@dataclass(frozen=True, slots=True, kw_only=True)\nclass VerifyOrWriteContext:\n    \"\"\"Shared launch context for canary verify/write kernels.\n\n    Fields:\n        canary_buf: Canary buffer this launch verifies or writes, shape [num_slots, slot_stride_bytes], uint8.\n            slot_stride_bytes is read from canary_buf.shape[1].","sourceCodeStart":95,"sourceCodeEnd":131,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/kernels/ops/kv_canary/verify.py#L95-L131","documentation":"The RealKvSource tensor holding the actual KV data must be at least 2-D (rows = tokens/pages, dim 1 = per-token bytes); a 1-D or 0-D tensor raises ValueError in __post_init__ because the kernel indexes rows by token.","triggerScenarios":"Passing a flattened 1-D view of the KV cache, or a scalar-like tensor, as RealKvSource.tensor.","commonSituations":"Flattening the cache for transport and forgetting to restore [tokens, bytes] shape; passing a single page's raw buffer without reshaping to [page_size, bytes_per_token].","solutions":["Reshape to [num_tokens, bytes_per_token]: kv.view(-1, num_bytes_per_token)","If passing a single page, use shape [page_size, num_bytes_per_token]"],"exampleFix":"# before\nsrc = RealKvSource(tensor=flat_buffer, ...)  # 1-D\n# after\nsrc = RealKvSource(tensor=flat_buffer.view(-1, bytes_per_token), ...)","handlingStrategy":"type-guard","validationCode":"assert tensor.ndim >= 2, tensor.shape","typeGuard":"def is_at_least_2d(t: torch.Tensor) -> bool:\n    return t.ndim >= 2","tryCatchPattern":null,"preventionTips":["Reshape flat KV buffers to [num_tokens, bytes_per_token] before constructing RealKvSource"],"tags":["kv-cache","shape-validation","tensor-rank"],"backgroundTag":"tensor-shape-validation","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}