sgl-project/sglang · critical · RuntimeError

PD decode DCP requires an MLA or hybrid-MLA KV pool.

Error message

PD decode DCP requires an MLA or hybrid-MLA KV pool.

What it means

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.

Source

Thrown at python/sglang/srt/disaggregation/common/conn.py:644

            raise RuntimeError(
                f"Page size mismatch: prefill server has page_size={info.page_size}, "
                f"but decode server has page_size={self.kv_args.page_size}. "
                f"Both servers must use the same --page-size value."
            )

        if (
            info.kv_cache_dtype is not None
            and info.kv_cache_dtype != self.kv_cache_dtype_str
        ):
            raise RuntimeError(
                f"KV cache dtype mismatch: prefill server has kv_cache_dtype={info.kv_cache_dtype}, "
                f"but decode server has kv_cache_dtype={self.kv_cache_dtype_str}. "
                f"Both servers must use the same --kv-cache-dtype value."
            )

        if self.dcp_size > 1:
            if not (self.is_mla_backend or self.is_hybrid_mla_backend):
                raise RuntimeError(
                    "PD decode DCP requires an MLA or hybrid-MLA KV pool."
                )
            if info.attn_cp_size != 1:
                raise RuntimeError(
                    "PD decode DCP currently requires prefill attention CP=1, "
                    f"got {info.attn_cp_size}."
                )

        self._resolve_rank_mapping(info)
        self.prefill_info_table[bootstrap_addr] = info
        logger.debug(f"Prefill parallel info for [{bootstrap_addr}]: {info}")
        return True

    def _resolve_rank_mapping(self, info: PrefillServerInfo) -> None:
        """Compute TP/CP/PP rank mapping and store on the PrefillServerInfo object.
        Deterministic for a given (bootstrap_addr, decode engine) pair."""
        # TP rank mapping
        if self.attn_tp_size == info.attn_tp_size:

View on GitHub (pinned to 0132848349)

Solutions

1. Remove/disable DCP (--dcp-size 1) if the model is GQA/MHA
2. Switch to an MLA-based model (DeepSeek V2/V3, etc.) if DCP is required
3. Verify self.is_mla_backend/is_hybrid_mla_backend resolves as expected for your model in server logs before enabling DCP

Example fix

# before
python -m sglang.launch_server --model qwen2.5 ... --dcp-size 2
# after
python -m sglang.launch_server --model qwen2.5 ... --dcp-size 1

if dcp_size > 1:
    assert model_is_mla or model_is_hybrid_mla, 'DCP requires MLA/hybrid-MLA KV pool'

def supports_dcp(model_backend: str) -> bool:
    return model_backend in ('mla', 'hybrid_mla')

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• SGLANG_DISAGG_STAGING_BUFFER is designed for non-MLA models
• PD peers must connect matching DCP ranks, got prefill={self.
• Unsupported PD DCP topology: {self.dcp_size} -> {dst_dcp_siz
• PD DCP source/destination KV geometry differs: src={src_toke
• PD decode DCP currently requires prefill attention CP=1, got

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