{"record":{"id":"5e1d79d4eaf0b04e","repo":"sgl-project/sglang","slug":"dsv4-target-and-draft-pools-must-use-the-same-unif","errorCode":null,"errorMessage":"DSV4 target and draft pools must use the same unified-KV mode","messagePattern":"DSV4 target and draft pools must use the same unified-KV mode","errorType":"validation","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/disaggregation/utils.py","lineNumber":1151,"sourceCode":"                c128_lens,\n                c128_item_lens,\n            )\n\n    # DSV4 NextN shares the target allocator, so target and draft use the same\n    # local SWA indices. Keep draft buffers in a separate positional component\n    # to avoid mixing them into the target's heterogeneous state layout, while\n    # reusing the existing SWA transport dispatch on both GPU and NPU.\n    if isinstance(token_to_kv_pool, DeepSeekV4TokenToKVPool) and isinstance(\n        draft_token_to_kv_pool, DeepSeekV4TokenToKVPool\n    ):\n        if not draft_token_to_kv_pool.compression_ratios or not all(\n            ratio == 0 for ratio in draft_token_to_kv_pool.compression_ratios\n        ):\n            raise RuntimeError(\n                \"DSV4 draft state transfer expects SWA-only NextN layers\"\n            )\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}\"","sourceCodeStart":1133,"sourceCodeEnd":1169,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/disaggregation/utils.py#L1133-L1169","documentation":"setup_state_kv_args validates that the DSV4 target pool and draft pool were built with the same _unified_kv flag (unified-KV mode on/off). If they differ, the state buffers to transfer have different layouts, so the shared-state transfer path is rejected.","triggerScenarios":"DSV4 disaggregation + speculative decoding where server args or pool constructors enable unified KV for the target model but not the draft (or vice versa), e.g. differing --enable-unified-kv-style flags applied only to one pool.","commonSituations":"Draft model config overriding a unified-KV flag; flag applied per-pool with inconsistent values; changing unified-KV default in a newer version affecting only one of the two pools.","solutions":["Set the same unified-KV mode for target and draft pools (align the flag/config that sets _unified_kv, e.g. enable it for both or neither)","Regenerate/align the draft (NextN) weights config to match the target's unified-KV setting","Disable speculative decoding if unified-KV modes cannot be aligned"],"exampleFix":"# before\ntarget pool: _unified_kv=True; draft pool: _unified_kv=False\n# after\ntarget pool: _unified_kv=True; draft pool: _unified_kv=True","handlingStrategy":"type-guard","validationCode":"assert target_pool._unified_kv == draft_pool._unified_kv, \"unified-KV mode mismatch\"","typeGuard":"def unified_kv_aligned(a, b) -> bool:\n    return a._unified_kv == b._unified_kv","tryCatchPattern":null,"preventionTips":["Apply unified-KV flags uniformly to target and draft configs","Add a startup assertion comparing both pools' mode"],"tags":["disaggregation","deepseek-v4","unified-kv","configuration-mismatch"],"backgroundTag":"configuration-mismatch","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}