{"record":{"id":"ab8af1e454333f03","repo":"sgl-project/sglang","slug":"dsv4-target-and-draft-pools-must-share-the-swa-ind","errorCode":null,"errorMessage":"DSV4 target and draft pools must share the SWA index mapping","messagePattern":"DSV4 target and draft pools must share the SWA index mapping","errorType":"validation","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/disaggregation/utils.py","lineNumber":1180,"sourceCode":"                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,\n            )\n            draft_geometry = (\n                draft_token_to_kv_pool.page_size,\n                draft_token_to_kv_pool.sliding_window,\n            )\n            if target_geometry != draft_geometry:\n                raise RuntimeError(\n                    \"DSV4 target and draft pools must share paged SWA 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_state_buf_infos()\n            )","sourceCodeStart":1162,"sourceCodeEnd":1198,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/disaggregation/utils.py#L1162-L1198","documentation":"In the non-unified-KV DSV4 path, target and draft pools must share the exact same full_to_swa_index_mapping object. If the draft pool has its own mapping, indices computed on one side would not resolve on the other during state transfer, so setup_state_kv_args raises RuntimeError.","triggerScenarios":"DSV4 disaggregation with spec decoding where the draft DeepSeekV4TokenToKVPool allocated its own full_to_swa_index_mapping tensor instead of being constructed with a reference to the target's mapping.","commonSituations":"Draft pool constructed independently (fresh mapping) rather than sharing the target pool's mapping; refactors that pass a copied/cloned mapping; version change in pool constructor defaults.","solutions":["Construct the draft pool with the target pool's full_to_swa_index_mapping object passed in (shared reference)","Upgrade/patch the code that builds the NextN pool so it shares the mapping","Disable speculative decoding if sharing cannot be arranged"],"exampleFix":"# before\ndraft_pool = DeepSeekV4TokenToKVPool(..., full_to_swa_index_mapping=None)  # own mapping\n# after\ndraft_pool = DeepSeekV4TokenToKVPool(..., full_to_swa_index_mapping=target_pool.full_to_swa_index_mapping)","handlingStrategy":"type-guard","validationCode":"assert target_pool.full_to_swa_index_mapping is draft_pool.full_to_swa_index_mapping, \"draft must share SWA index mapping\"","typeGuard":"def shares_swa_mapping(target, draft) -> bool:\n    return target.full_to_swa_index_mapping is draft.full_to_swa_index_mapping","tryCatchPattern":null,"preventionTips":["Pass the target pool's mapping into the draft pool constructor","Never clone the mapping for the draft pool"],"tags":["disaggregation","deepseek-v4","swa","index-mapping"],"backgroundTag":"configuration-mismatch","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}