sgl-project/sglang · critical · RuntimeError

Unsupported PD DCP topology: {self.dcp_size} -> {dst_dcp_siz

Error message

Unsupported PD DCP topology: {self.dcp_size} -> {dst_dcp_size}

What it means

requires_dcp_relayout returns whether KV must be relaid-out across DCP ranks between prefill and decode. Equal sizes pair 1:1 (no relayout) and 1->N with MLA backends can relayout; every other topology combination — notably N->1 or N->M — is unsupported and raises RuntimeError.

Source

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

        )

    def requires_dcp_relayout(self, dst_dcp_size: int, dst_dcp_rank: int) -> bool:
        if self.dcp_size == dst_dcp_size:
            if self.dcp_rank != dst_dcp_rank:
                raise RuntimeError(
                    "PD peers must connect matching DCP ranks, got "
                    f"prefill={self.dcp_rank}, decode={dst_dcp_rank}"
                )
            return False

        if (
            self.dcp_size == 1
            and dst_dcp_size > 1
            and (self.is_mla_backend or self.is_hybrid_mla_backend)
        ):
            return True

        raise RuntimeError(
            f"Unsupported PD DCP topology: {self.dcp_size} -> {dst_dcp_size}"
        )

    def prepare_dcp_token_item_lens(self, dst_page_item_lens: List[int]) -> List[int]:
        page_size = self.kv_args.page_size
        src_token_lens = [
            item_len // page_size for item_len in self.kv_args.kv_item_lens
        ]
        dst_token_lens = [item_len // page_size for item_len in dst_page_item_lens]
        if src_token_lens != dst_token_lens:
            raise RuntimeError(
                "PD DCP source/destination KV geometry differs: "
                f"src={src_token_lens}, dst={dst_token_lens}"
            )
        return src_token_lens

    def check_status(self, bootstrap_room: int) -> KVPoll:
        return self.request_status[bootstrap_room]

View on GitHub (pinned to 0132848349)

Solutions

1. Set the same --dcp-size (context-parallel size) on prefill and decode instances so ranks pair 1:1
2. If asymmetric sizes are required, keep prefill dcp_size == 1 and use an MLA (or hybrid MLA) backend so the 1->N relayout path applies
3. Otherwise re-topologize the cluster so sizes match; N->M and N->1 are not supported

ok = (dcp_size == dst_dcp_size) or (dcp_size == 1 and dst_dcp_size > 1 and is_mla_backend)\nassert ok, f'unsupported PD DCP topology {dcp_size}->{dst_dcp_size}'

When it happens

Trigger: PD disaggregation where decode DCP size differs from prefill DCP size and the pair is not (1 -> N with an MLA or hybrid-MLA backend), e.g. prefill --dcp-size 2 with decode --dcp-size 1, or 2 -> 4.

Common situations: Operator scales only one side of the PD cluster (adds CP ranks to prefill but not decode, or vice versa); reusing launch scripts with different tensor/context parallel settings per side; non-MLA backend combined with asymmetric DCP.

Related errors

• PD peers must connect matching DCP ranks, got prefill={self.
• PD DCP source/destination KV geometry differs: src={src_toke
• PD decode DCP requires an MLA or hybrid-MLA KV pool.
• PD decode DCP currently requires prefill attention CP=1, got
• PD DCP transfer requires decode_prefix_len to align to the v

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