sgl-project/sglang · error · ValueError

PD decode DCP requires --disaggregation-transfer-backend moo

Error message

PD decode DCP requires --disaggregation-transfer-backend mooncake, nixl, or fake for synthetic benchmarking, got {}.

What it means

Prefill-decode disaggregation with decode-side cache-protected (DCP) transfer requires a real KV transfer engine (mooncake or nixl) or the fake backend for synthetic benchmarks. Other transfer backends (e.g. ascends etc.) cannot perform the DCP relayout.

Source

Thrown at python/sglang/srt/arg_groups/pd_disaggregation_hook.py:58

            "with MC_FORCE_TCP=1 (TCP transport, no RDMA)"
        )

    if cfg.disaggregation_mode == "prefill" and cfg.dcp_size > 1:
        logger.warning(
            "DCP on a PD prefill server is supported when prefill and decode "
            "use the same DCP layout, but it usually adds communication "
            "overhead without improving prefill performance."
        )

    if cfg.disaggregation_mode == "decode" and cfg.dcp_size > 1:
        # Fake transfer moves no KV and is only used for synthetic decode
        # benchmarks, so it does not need the DCP relayout from Mooncake/NIXL.
        if cfg.disaggregation_transfer_backend not in (
            "mooncake",
            "nixl",
            "fake",
        ):
            raise ValueError(
                "PD decode DCP requires --disaggregation-transfer-backend "
                "mooncake, nixl, or fake for synthetic benchmarking, got "
                f"{cfg.disaggregation_transfer_backend!r}."
            )
        if cfg.disaggregation_decode_enable_radix_cache:
            raise ValueError(
                "PD decode DCP currently requires chunk cache; "
                "--disaggregation-decode-enable-radix-cache is not supported."
            )
        if cfg.enable_hierarchical_cache:
            raise ValueError(
                "PD decode DCP currently requires chunk cache; "
                "--enable-hierarchical-cache is not supported."
            )

    if cfg.disaggregation_mode == "decode":
        if cfg.disaggregation_decode_enable_radix_cache:
            if cfg.enable_hisparse:

View on GitHub (pinned to 0132848349)

Solutions

1. Set --disaggregation-transfer-backend mooncake (production default)
2. Or nixl if that is your stack
3. Use fake only for synthetic benchmarking

Example fix

# before
--disaggregation-transfer-backend <other> <dcp-flags>
# after
--disaggregation-transfer-backend mooncake <dcp-flags>

if dcp_enabled:
    assert cfg.disaggregation_transfer_backend in ("mooncake", "nixl", "fake")

When it happens

Trigger: Enabling PD decode DCP with --disaggregation-transfer-backend set to anything besides mooncake/nixl/fake.

Common situations: Enabling a DCP feature flag on a cluster configured with a custom or vendor-specific transfer backend.

Related errors

• PD decode DCP currently requires chunk cache; --disaggregati
• PD decode DCP currently requires chunk cache; --enable-hiera
• SGLANG_DISAGG_STAGING_BUFFER requires disaggregation_transfe
• --enable-dsa-cache-layer-split currently only supports the m
• --disaggregation-decode-retraction-backup=host_pool is only

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