sgl-project/sglang · error · RuntimeError

DSV4 target and draft pools must share paged SWA geometry: t

Error message

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

What it means

In the non-unified-KV DSV4 path, target and draft pools must have identical (page_size, sliding_window) tuples. Mismatched paged SWA geometry would make transferred state unusable, so setup_state_kv_args raises RuntimeError showing both geometry tuples.

Source

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

            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,
            )
            draft_geometry = (
                draft_token_to_kv_pool.page_size,
                draft_token_to_kv_pool.sliding_window,
            )
            if target_geometry != draft_geometry:
                raise RuntimeError(
                    "DSV4 target and draft pools must share paged SWA geometry: "
                    f"target={target_geometry}, draft={draft_geometry}"
                )
            draft_ptrs, draft_lens, draft_item_lens = (
                draft_token_to_kv_pool.get_state_buf_infos()
            )
            draft_state_type = StateType.SWA

        if draft_ptrs:
            append_state_component(
                kv_args,
                draft_state_type,
                draft_ptrs,
                draft_lens,
                draft_item_lens,
            )

    if (

View on GitHub (pinned to 0132848349)

Solutions

1. Set identical page_size and sliding_window for target and draft pools (align server args / model configs)
2. Remove draft-specific page-size or window overrides
3. Disable speculative decoding or disaggregation if they cannot be aligned

Example fix

# before
target: (page_size=1, sliding_window=4096); draft: (page_size=32, sliding_window=4096)
# after
target: (page_size=32, sliding_window=4096); draft: (page_size=32, sliding_window=4096)

assert (target_pool.page_size, target_pool.sliding_window) == (draft_pool.page_size, draft_pool.sliding_window)

def paged_swa_geometry_equal(a, b) -> bool:
    return (a.page_size, a.sliding_window) == (b.page_size, b.sliding_window)

When it happens

Trigger: DSV4 disaggregation with spec decoding where the draft pool's page_size or sliding_window differs from the target pool's (e.g. --page-size set per pool, or draft config with a different window).

Common situations: Different --page-size applied to target vs draft; NextN draft model with its own sliding_window in config; changing chunked-prefix/page-size args only for one pool.

Related errors

• Page size mismatch: prefill server has page_size={info.page_
• SGLANG_DISAGG_STAGING_BUFFER requires a positive chunked_pre
• DSV4 draft state transfer expects SWA-only NextN layers
• DSV4 target and draft pools must use the same unified-KV mod
• DSV4 target and draft pools must share SWA ring geometry: ta

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