{"record":{"id":"f6ea5bab90db51f9","repo":"sgl-project/sglang","slug":"dsv4-target-and-draft-pools-must-share-swa-ring-ge","errorCode":null,"errorMessage":"DSV4 target and draft pools must share SWA ring geometry: target={target_geometry}, draft={draft_geometry}","messagePattern":"DSV4 target and draft pools must share SWA ring geometry: target=(.+?), draft=(.+?)","errorType":"validation","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/disaggregation/utils.py","lineNumber":1167,"sourceCode":"            )\n        if token_to_kv_pool._unified_kv != draft_token_to_kv_pool._unified_kv:\n            raise RuntimeError(\n                \"DSV4 target and draft pools must use the same unified-KV mode\"\n            )\n\n        if token_to_kv_pool._unified_kv:\n            target_geometry = (\n                token_to_kv_pool.unified_swa_window,\n                token_to_kv_pool.unified_swa_ring_size,\n                token_to_kv_pool.unified_swa_pages,\n            )\n            draft_geometry = (\n                draft_token_to_kv_pool.unified_swa_window,\n                draft_token_to_kv_pool.unified_swa_ring_size,\n                draft_token_to_kv_pool.unified_swa_pages,\n            )\n            if target_geometry != draft_geometry:\n                raise RuntimeError(\n                    \"DSV4 target and draft pools must share SWA ring geometry: \"\n                    f\"target={target_geometry}, draft={draft_geometry}\"\n                )\n            draft_ptrs, draft_lens, draft_item_lens = (\n                draft_token_to_kv_pool.get_unified_swa_ring_buf_infos()\n            )\n            draft_state_type = StateType.SWA_RING\n        else:\n            if (\n                token_to_kv_pool.full_to_swa_index_mapping\n                is not draft_token_to_kv_pool.full_to_swa_index_mapping\n            ):\n                raise RuntimeError(\n                    \"DSV4 target and draft pools must share the SWA index mapping\"\n                )\n            target_geometry = (\n                token_to_kv_pool.page_size,\n                token_to_kv_pool.sliding_window,","sourceCodeStart":1149,"sourceCodeEnd":1185,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/disaggregation/utils.py#L1149-L1185","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"# before\ntarget: (swa_window=4096, ring=8, pages=512); draft: (swa_window=2048, ring=4, pages=256)\n# after\ntarget: (swa_window=4096, ring=8, pages=512); draft: (swa_window=4096, ring=8, pages=512)","handlingStrategy":"type-guard","validationCode":"tg = (lambda p: (p.unified_swa_window, p.unified_swa_ring_size, p.unified_swa_pages))\nassert tg(target_pool) == tg(draft_pool), f\"geometry mismatch {tg(target_pool)} vs {tg(draft_pool)}\"","typeGuard":"def swa_ring_geometry_equal(a, b) -> bool:\n    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)","tryCatchPattern":null,"preventionTips":["Derive SWA ring parameters from one shared config object for both pools","Fail fast at pool construction if geometry differs"],"tags":["disaggregation","deepseek-v4","swa","geometry-mismatch"],"backgroundTag":"configuration-mismatch","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}