sgl-project/sglang · error · ValueError

kv-canary: SWA slot {slot} is outside full_to_swa_index_mapp

Error message

kv-canary: SWA slot {slot} is outside full_to_swa_index_mapping length {lut_len}

What it means

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.

Source

Thrown at python/sglang/kernels/ops/kv_canary/plan_ref.py:121

def _write_num_valid_and_enable(
    *,
    verify_plan_out: VerifyPlan,
    requested: int,
    verify_capacity: int,
) -> None:
    overflow = requested > verify_capacity
    clamped = verify_capacity if overflow else requested
    enable = 0 if overflow else 1
    verify_plan_out.verify_num_valid.fill_(int(clamped))
    verify_plan_out.enable.fill_(int(enable))


def _swa_translate_slot(*, slot: int, lut: torch.Tensor) -> int:
    if slot < 0:
        return slot
    lut_len = int(lut.shape[0])
    if slot >= lut_len:
        raise ValueError(
            f"kv-canary: SWA slot {slot} is outside full_to_swa_index_mapping length {lut_len}"
        )
    return int(lut[slot].item())


def _materialize_verify_entries(
    *,
    verify_plan_out: VerifyPlan,
    req_pool_indices_host: torch.Tensor,
    prefix_lens_host: torch.Tensor,
    req_to_token_host: torch.Tensor,
    swa_window_size: int,
    lut: Optional[torch.Tensor],
    verify_capacity: int,
    work_device: torch.device,
    bs: int,
    expected_token_pool_host: Optional[torch.Tensor],
    req_to_verify_expected_tokens_valid_lens_host: Optional[torch.Tensor],

View on GitHub (pinned to 0132848349)

Solutions

1. Check the producer of the slot indices — a stale or overflowing slot is usually the real bug, not the LUT
2. Ensure full_to_swa_index_mapping is sized to cover all allocatable full-attention slots (token capacity / page size)
3. Reproduce with the torch reference (this raise) to dump the offending slot and trace which request produced it

Example fix

# before
lut = full_to_swa[:num_allocated_pages]  # truncated
# after
lut = full_to_swa  # full table covering all slots

if slot >= 0:
    assert slot < full_to_swa_index_mapping.shape[0], f"slot {slot} vs LUT {full_to_swa_index_mapping.shape[0]}"

try:
    launch_ref(...)
except ValueError as e:
    if 'outside full_to_swa_index_mapping' in str(e):
        dump_slot_provenance()  # inspect producer of the bad slot
    raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Invalid {debug_name} write range: local=[{local_start_index}
• recent_window_tokens must be non-negative or None
• recent_window_tokens must be >= 0 or None
• WindowedAttentionKVCache holds only the trailing window and
• v_cache must be provided

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/7249846e6ab0f41e. Report an issue: GitHub.