sgl-project/sglang · error · ValueError

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

Error message

--disaggregation-decode-enable-radix-cache is incompatible with --enable-hisparse

What it means

In decode-mode PD disaggregation, --disaggregation-decode-enable-radix-cache cannot be combined with --enable-hisparse because hisparse changes cache layout in ways the decode radix-cache path does not support.

Source

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

                "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(
                    "--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(

View on GitHub (pinned to 0132848349)

Solutions

Drop --enable-hisparse
Or drop --disaggregation-decode-enable-radix-cache

Example fix

# before
--disaggregation-mode decode --disaggregation-decode-enable-radix-cache --enable-hisparse
# after
--disaggregation-mode decode --disaggregation-decode-enable-radix-cache

Defensive patterns

Strategy: validation

Validate before calling

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

Prevention

Build a pairwise compatibility matrix of disaggregation flags and validate pre-launch

When it happens

Trigger: --disaggregation-mode decode with both --disaggregation-decode-enable-radix-cache and --enable-hisparse set.

Common situations: Turning on hisparse for sparse KV handling while also enabling decode radix cache for prefix reuse.

Related errors

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