{"record":{"id":"7d4529420110ffdb","repo":"sgl-project/sglang","slug":"pd-decode-dcp-requires-an-mla-or-hybrid-mla-kv-poo","errorCode":null,"errorMessage":"PD decode DCP requires an MLA or hybrid-MLA KV pool.","messagePattern":"PD decode DCP requires an MLA or hybrid-MLA KV pool\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"python/sglang/srt/disaggregation/common/conn.py","lineNumber":644,"sourceCode":"            raise RuntimeError(\n                f\"Page size mismatch: prefill server has page_size={info.page_size}, \"\n                f\"but decode server has page_size={self.kv_args.page_size}. \"\n                f\"Both servers must use the same --page-size value.\"\n            )\n\n        if (\n            info.kv_cache_dtype is not None\n            and info.kv_cache_dtype != self.kv_cache_dtype_str\n        ):\n            raise RuntimeError(\n                f\"KV cache dtype mismatch: prefill server has kv_cache_dtype={info.kv_cache_dtype}, \"\n                f\"but decode server has kv_cache_dtype={self.kv_cache_dtype_str}. \"\n                f\"Both servers must use the same --kv-cache-dtype value.\"\n            )\n\n        if self.dcp_size > 1:\n            if not (self.is_mla_backend or self.is_hybrid_mla_backend):\n                raise RuntimeError(\n                    \"PD decode DCP requires an MLA or hybrid-MLA KV pool.\"\n                )\n            if info.attn_cp_size != 1:\n                raise RuntimeError(\n                    \"PD decode DCP currently requires prefill attention CP=1, \"\n                    f\"got {info.attn_cp_size}.\"\n                )\n\n        self._resolve_rank_mapping(info)\n        self.prefill_info_table[bootstrap_addr] = info\n        logger.debug(f\"Prefill parallel info for [{bootstrap_addr}]: {info}\")\n        return True\n\n    def _resolve_rank_mapping(self, info: PrefillServerInfo) -> None:\n        \"\"\"Compute TP/CP/PP rank mapping and store on the PrefillServerInfo object.\n        Deterministic for a given (bootstrap_addr, decode engine) pair.\"\"\"\n        # TP rank mapping\n        if self.attn_tp_size == info.attn_tp_size:","sourceCodeStart":626,"sourceCodeEnd":662,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/disaggregation/common/conn.py#L626-L662","documentation":"Raised in try_ensure_parallel_info when decode-side context-parallel KV (dcp_size > 1) is configured but the decode KV pool is not an MLA or hybrid-MLA pool. DCP (decode context parallel) splits MLA's compressed latent KV across ranks; GQA/MHA pools cannot be sharded this way, so the configuration is rejected.","triggerScenarios":"Launching a decode server with dcp_size > 1 (e.g. --dcp-size 2 / dcp parallelism enabled) while running a GQA/MHA model whose allocator is not MLA or hybrid-MLA.","commonSituations":"Copy-pasting DCP flags from a DeepSeek-MLA deployment onto a Llama/Qwen GQA deployment; enabling decode CP for throughput without checking model architecture support.","solutions":["Remove/disable DCP (--dcp-size 1) if the model is GQA/MHA","Switch to an MLA-based model (DeepSeek V2/V3, etc.) if DCP is required","Verify self.is_mla_backend/is_hybrid_mla_backend resolves as expected for your model in server logs before enabling DCP"],"exampleFix":"# before\npython -m sglang.launch_server --model qwen2.5 ... --dcp-size 2\n# after\npython -m sglang.launch_server --model qwen2.5 ... --dcp-size 1","handlingStrategy":"validation","validationCode":"if dcp_size > 1:\n    assert model_is_mla or model_is_hybrid_mla, 'DCP requires MLA/hybrid-MLA KV pool'","typeGuard":"def supports_dcp(model_backend: str) -> bool:\n    return model_backend in ('mla', 'hybrid_mla')","tryCatchPattern":null,"preventionTips":["Gate DCP flags on model family in launch scripts","Keep a compatibility matrix of model type vs parallel features"],"tags":["disaggregation","dcp","context-parallel","mla","unsupported-feature"],"backgroundTag":"unsupported-hardware-feature-combo","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}