sgl-project/sglang · error · ValueError

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

Error message

--disaggregation-decode-enable-radix-cache is incompatible with speculative decoding (--speculative-algorithm {})

What it means

Decode-side radix cache in PD disaggregation is incompatible with speculative decoding: prefill happens on a different node, so draft-model KV needed by EAGLE/NEXTN-style speculation cannot be populated by the decode-side radix cache.

Source

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

            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,
                "handle_pd_disaggregation",
                disable_radix_cache=False,
            )
            logger.warning("EXPERIMENTAL: Radix cache is enabled for decode server")
        else:

View on GitHub (pinned to 0132848349)

Solutions

Remove --disaggregation-decode-enable-radix-cache when using speculative decoding in decode mode
Or disable speculative decoding if decode radix cache matters more

Example fix

# before
--disaggregation-mode decode --disaggregation-decode-enable-radix-cache --speculative-algorithm EAGLE
# after
--disaggregation-mode decode --speculative-algorithm EAGLE

Defensive patterns

Strategy: validation

Validate before calling

if cfg.disaggregation_mode == "decode" and cfg.disaggregation_decode_enable_radix_cache:
    assert cfg.speculative_algorithm is None

Prevention

Remember speculation needs prefill-side draft KV; decode radix cache cannot provide it in PD setups

When it happens

Trigger: --disaggregation-mode decode with --disaggregation-decode-enable-radix-cache and any --speculative-algorithm set (EAGLE, EAGLE3, NEXTN, ...).

Common situations: Enabling prefix caching on decode nodes of a disaggregated deployment that also serves with speculative decoding.

Related errors

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