sgl-project/sglang · error · RuntimeError

DSV4 target and draft pools must share SWA ring geometry…

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.

Solutions

Align sliding window, ring size, and page count config so both pools' (unified_swa_window, unified_swa_ring_size, unified_swa_pages) tuples match
Remove draft-specific SWA overrides in the speculative model config
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)

Defensive patterns

Strategy: type-guard

Validate before calling

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)}"

Type guard

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)

Prevention

Derive SWA ring parameters from one shared config object for both pools
Fail fast at pool construction if geometry differs

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

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

Appendix: 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)