{"record":{"id":"7249846e6ab0f41e","repo":"sgl-project/sglang","slug":"kv-canary-swa-slot-slot-is-outside-full-to-swa","errorCode":null,"errorMessage":"kv-canary: SWA slot {slot} is outside full_to_swa_index_mapping length {lut_len}","messagePattern":"kv-canary: SWA slot (.+?) is outside full_to_swa_index_mapping length (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/kernels/ops/kv_canary/plan_ref.py","lineNumber":121,"sourceCode":"def _write_num_valid_and_enable(\n    *,\n    verify_plan_out: VerifyPlan,\n    requested: int,\n    verify_capacity: int,\n) -> None:\n    overflow = requested > verify_capacity\n    clamped = verify_capacity if overflow else requested\n    enable = 0 if overflow else 1\n    verify_plan_out.verify_num_valid.fill_(int(clamped))\n    verify_plan_out.enable.fill_(int(enable))\n\n\ndef _swa_translate_slot(*, slot: int, lut: torch.Tensor) -> int:\n    if slot < 0:\n        return slot\n    lut_len = int(lut.shape[0])\n    if slot >= lut_len:\n        raise ValueError(\n            f\"kv-canary: SWA slot {slot} is outside full_to_swa_index_mapping length {lut_len}\"\n        )\n    return int(lut[slot].item())\n\n\ndef _materialize_verify_entries(\n    *,\n    verify_plan_out: VerifyPlan,\n    req_pool_indices_host: torch.Tensor,\n    prefix_lens_host: torch.Tensor,\n    req_to_token_host: torch.Tensor,\n    swa_window_size: int,\n    lut: Optional[torch.Tensor],\n    verify_capacity: int,\n    work_device: torch.device,\n    bs: int,\n    expected_token_pool_host: Optional[torch.Tensor],\n    req_to_verify_expected_tokens_valid_lens_host: Optional[torch.Tensor],","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/kernels/ops/kv_canary/plan_ref.py#L103-L139","documentation":"While materializing verify/write metadata, the SWA (sliding-window attention) slot translator looks up full_to_swa_index_mapping[slot]; any non-negative slot must be within the LUT's length. A slot at or beyond the LUT means the full-attention slot index is out of range for the SWA mapping table, indicating corrupted indices or an undersized mapping.","triggerScenarios":"A plan output or input metadata contains a full-attention slot index >= full_to_swa_index_mapping.shape[0]; raised from _materialize_verify_entries or _materialize_write_metadata in the torch reference planner.","commonSituations":"SWA LUT sized to the current number of allocated pages while slot indices reference freed/stale pages; ring-buffer overflow or index reuse bugs; passing a truncated mapping tensor after memory pool reconfiguration.","solutions":["Check the producer of the slot indices — a stale or overflowing slot is usually the real bug, not the LUT","Ensure full_to_swa_index_mapping is sized to cover all allocatable full-attention slots (token capacity / page size)","Reproduce with the torch reference (this raise) to dump the offending slot and trace which request produced it"],"exampleFix":"# before\nlut = full_to_swa[:num_allocated_pages]  # truncated\n# after\nlut = full_to_swa  # full table covering all slots","handlingStrategy":"validation","validationCode":"if slot >= 0:\n    assert slot < full_to_swa_index_mapping.shape[0], f\"slot {slot} vs LUT {full_to_swa_index_mapping.shape[0]}\"","typeGuard":null,"tryCatchPattern":"try:\n    launch_ref(...)\nexcept ValueError as e:\n    if 'outside full_to_swa_index_mapping' in str(e):\n        dump_slot_provenance()  # inspect producer of the bad slot\n    raise","preventionTips":["Size the SWA LUT to cover all allocatable full slots","Treat this raise as a symptom of index corruption upstream, not a sizing knob"],"tags":["kv-cache","index-out-of-range","sliding-window","lut"],"backgroundTag":"index-out-of-bounds","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}