sgl-project/sglang · error · ValueError

--enable-dsa-cache-layer-split is only supported on PD prefi

Error message

--enable-dsa-cache-layer-split is only supported on PD prefill workers. Non-PD workers also run decode and require ordinary local decode cache semantics.

What it means

--enable-dsa-cache-layer-split changes local cache semantics in a way that only PD prefill workers can tolerate: a non-PD worker also runs decode locally and needs ordinary local decode cache, so the flag is rejected when disaggregation_mode is neither 'prefill' nor 'decode' (i.e. not PD at all).

Source

Thrown at python/sglang/srt/server_args.py:5934

                    )
                    self._set_default_dsa_backends(major)

                if cfg.enable_prefill_cp:
                    assert (
                        cfg.disaggregation_mode != "decode"
                    ), "CP is only supported for prefill when PD disaggregation, please remove --enable-prefill-cp."
                if (
                    cfg.enable_dsa_cache_layer_split
                    and cfg.disaggregation_mode != "prefill"
                ):
                    if cfg.disaggregation_mode == "decode":
                        raise ValueError(
                            "--enable-dsa-cache-layer-split is not supported on "
                            "decode workers. This flag is a prefill-CP "
                            "optimization; decode receives full cache shards "
                            "through PD transfer."
                        )
                    raise ValueError(
                        "--enable-dsa-cache-layer-split is only supported on PD "
                        "prefill workers. Non-PD workers also run decode and "
                        "require ordinary local decode cache semantics."
                    )
                if cfg.enable_dsa_cache_layer_split and (
                    not cfg.enable_prefill_cp or cfg.cp_strategy != "interleave"
                ):
                    raise ValueError(
                        "--enable-dsa-cache-layer-split requires "
                        "--enable-prefill-cp and --cp-strategy interleave "
                        "(or legacy --enable-nsa-prefill-context-parallel with "
                        "--nsa-prefill-cp-mode round-robin-split)."
                    )
                # Layer split relies on the mooncake all-CP-rank KV/indexer
                # transfer path. mori/nixl support is a temporary limitation
                # and will be added later by the community.
                if (
                    cfg.enable_dsa_cache_layer_split

View on GitHub (pinned to 0132848349)

Solutions

Remove --enable-dsa-cache-layer-split unless running a PD prefill worker
Set up prefill/decode disaggregation (--disaggregation-mode prefill) if you want this optimization

Example fix

# before
--enable-dsa-cache-layer-split  # standalone server
# after
# (flag removed; or run a PD prefill worker)

Defensive patterns

Strategy: validation

Validate before calling

mode = args.get("disaggregation_mode")
if args.get("enable_dsa_cache_layer_split") and mode not in ("prefill", "decode"):
    args["enable_dsa_cache_layer_split"] = False

Prevention

Only carry DSA cache-layer-split flags into real PD prefill deployments
Strip experimental flags from dev/standalone configs via an allowlist

When it happens

Trigger: Passing --enable-dsa-cache-layer-split on a standalone (non-disaggregated) server, where disaggregation_mode is None/other.

Common situations: Trying the optimization on a single combined server before deploying PD; leftover flags from a PD prefill config on a dev box.

Related errors

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