sgl-project/sglang · error · RuntimeError

DSV4 target and draft pools must share SWA ring geometry: ta

Error message

DSV4 target and draft pools must share SWA ring geometry: target={target_geometry}, draft={draft_geometry}

What it means

When both DSV4 pools use unified KV, setup_state_kv_args requires identical SWA ring geometry (unified_swa_window, unified_swa_ring_size, unified_swa_pages) between target and draft. Different geometry means the ring buffers being registered for transfer do not correspond, so it raises RuntimeError with both tuples.

Source

Thrown at python/sglang/srt/disaggregation/utils.py:1167

            )
        if token_to_kv_pool._unified_kv != draft_token_to_kv_pool._unified_kv:
            raise RuntimeError(
                "DSV4 target and draft pools must use the same unified-KV mode"
            )

        if token_to_kv_pool._unified_kv:
            target_geometry = (
                token_to_kv_pool.unified_swa_window,
                token_to_kv_pool.unified_swa_ring_size,
                token_to_kv_pool.unified_swa_pages,
            )
            draft_geometry = (
                draft_token_to_kv_pool.unified_swa_window,
                draft_token_to_kv_pool.unified_swa_ring_size,
                draft_token_to_kv_pool.unified_swa_pages,
            )
            if target_geometry != draft_geometry:
                raise RuntimeError(
                    "DSV4 target and draft pools must share SWA ring geometry: "
                    f"target={target_geometry}, draft={draft_geometry}"
                )
            draft_ptrs, draft_lens, draft_item_lens = (
                draft_token_to_kv_pool.get_unified_swa_ring_buf_infos()
            )
            draft_state_type = StateType.SWA_RING
        else:
            if (
                token_to_kv_pool.full_to_swa_index_mapping
                is not draft_token_to_kv_pool.full_to_swa_index_mapping
            ):
                raise RuntimeError(
                    "DSV4 target and draft pools must share the SWA index mapping"
                )
            target_geometry = (
                token_to_kv_pool.page_size,
                token_to_kv_pool.sliding_window,

View on GitHub (pinned to 0132848349)

Solutions

1. Align sliding window, ring size, and page count config so both pools' (unified_swa_window, unified_swa_ring_size, unified_swa_pages) tuples match
2. Remove draft-specific SWA overrides in the speculative model config
3. Disable speculative decoding or unified-KV disaggregation if geometry cannot match

Example fix

# before
target: (swa_window=4096, ring=8, pages=512); draft: (swa_window=2048, ring=4, pages=256)
# after
target: (swa_window=4096, ring=8, pages=512); draft: (swa_window=4096, ring=8, pages=512)

tg = (lambda p: (p.unified_swa_window, p.unified_swa_ring_size, p.unified_swa_pages))
assert tg(target_pool) == tg(draft_pool), f"geometry mismatch {tg(target_pool)} vs {tg(draft_pool)}"

def swa_ring_geometry_equal(a, b) -> bool:
    return (a.unified_swa_window, a.unified_swa_ring_size, a.unified_swa_pages) == (b.unified_swa_window, b.unified_swa_ring_size, b.unified_swa_pages)

When it happens

Trigger: DSV4 unified-KV disaggregation with speculative decoding where the draft pool was constructed with a different sliding-window size, ring size, or page count than the target pool.

Common situations: Draft model config specifying its own sliding window / chunked prefix settings; manually tuned SWA ring parameters only for the target; default geometry differing between target and NextN pool constructors.

Related errors

• DSV4 draft state transfer expects SWA-only NextN layers
• DSV4 target and draft pools must share the SWA index mapping
• PD DCP source/destination KV geometry differs: src={src_toke
• PD state transfer does not support TP-mismatched non-MLA SWA
• DSV4 target and draft pools must use the same unified-KV mod

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