sgl-project/sglang · error · ValueError

--disaggregation-decode-enable-radix-cache is incompatible w

Error message

--disaggregation-decode-enable-radix-cache is incompatible with --disaggregation-transfer-backend fake

What it means

Decode-side radix cache in PD disaggregation does not work with the fake transfer backend, because fake skips real KV transfer so the radix cache would serve unverified state. SGLang rejects the combination at startup.

Source

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

            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(
                    "--disaggregation-decode-enable-radix-cache is incompatible "
                    "with speculative decoding "
                    f"(--speculative-algorithm {cfg.speculative_algorithm})"
                )
            from sglang.srt.arg_groups.overrides import resolved_view

            if resolved_view(server_args).enable_dp_attention:
                logger.warning(
                    "EXPERIMENTAL: Decode radix cache with DP attention. "
                    "Requires prefix-aware DP rank routing for optimal cache hits."
                )
            declare_resolution(
                server_args,

View on GitHub (pinned to 0132848349)

Solutions

1. Use a real transfer backend (mooncake/nixl) when radix cache is enabled
2. Or disable --disaggregation-decode-enable-radix-cache for fake-backend benchmarking

Example fix

# before
--disaggregation-mode decode --disaggregation-decode-enable-radix-cache --disaggregation-transfer-backend fake
# after
--disaggregation-mode decode --disaggregation-decode-enable-radix-cache --disaggregation-transfer-backend mooncake

if cfg.disaggregation_mode == "decode" and cfg.disaggregation_decode_enable_radix_cache:
    assert cfg.disaggregation_transfer_backend != "fake"

When it happens

Trigger: --disaggregation-mode decode with --disaggregation-decode-enable-radix-cache and --disaggregation-transfer-backend fake.

Common situations: Reusing a synthetic benchmarking config (fake backend) while toggling radix cache flags on for a load test.

Related errors

• PD decode DCP currently requires chunk cache; --disaggregati
• --disaggregation-decode-enable-radix-cache is incompatible w
• --disaggregation-decode-enable-radix-cache is incompatible w
• PD decode DCP currently requires chunk cache; --enable-hiera
• MiniCPM sparse attention does not support PD disaggregation

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