sgl-project/sglang · error · ValueError

PD decode DCP currently requires chunk cache; --enable-hiera

Error message

PD decode DCP currently requires chunk cache; --enable-hierarchical-cache is not supported.

What it means

PD decode DCP requires chunk cache, so hierarchical cache (--enable-hierarchical-cache) is incompatible with it: HiCache layers KV across media with a layout DCP's relayout cannot handle.

Source

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

        # 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:
                raise ValueError(
                    "--disaggregation-decode-enable-radix-cache is incompatible "
                    "with --enable-hisparse"
                )
            if cfg.disaggregation_transfer_backend == "fake":
                raise ValueError(
                    "--disaggregation-decode-enable-radix-cache is incompatible "
                    "with --disaggregation-transfer-backend fake"
                )
            if cfg.speculative_algorithm is not None:
                raise ValueError(

View on GitHub (pinned to 0132848349)

Solutions

  1. Disable --enable-hierarchical-cache on decode nodes using DCP
  2. Or drop DCP if hierarchical cache is a hard requirement

Example fix

# before
<DCP flags> --enable-hierarchical-cache
# after
<DCP flags>
Defensive patterns

Strategy: validation

Validate before calling

if dcp_enabled:
    cfg.enable_hierarchical_cache = False

Prevention

When it happens

Trigger: Enabling PD decode DCP together with --enable-hierarchical-cache.

Common situations: Combining hierarchical cache (for local KV reuse across restarts) with DCP on decode nodes in a disaggregated cluster.

Related errors

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