sgl-project/sglang · error · ValueError

--enable-dsa-cache-layer-split requires --enable-prefill-cp

Error message

--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).

What it means

The DSA cache-layer-split implementation depends on prefill context parallelism with the interleaved CP strategy; ServerArgs requires --enable-prefill-cp and --cp-strategy interleave (legacy equivalents: --enable-nsa-prefill-context-parallel with --nsa-prefill-cp-mode round-robin-split) when the flag is set.

Source

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

                    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
                    and cfg.disaggregation_transfer_backend != "mooncake"
                ):
                    raise ValueError(
                        "--enable-dsa-cache-layer-split currently only supports "
                        "the mooncake transfer backend (mooncake / mooncake_tcp). "
                        f"Got --disaggregation-transfer-backend "
                        f"{cfg.disaggregation_transfer_backend!r}. mori/nixl "
                        "support will be added later by the community."

View on GitHub (pinned to 0132848349)

Solutions

Add --enable-prefill-cp and --cp-strategy interleave
Or use the legacy pair --enable-nsa-prefill-context-parallel with --nsa-prefill-cp-mode round-robin-split
Remove --enable-dsa-cache-layer-split if you cannot use prefill CP

Example fix

# before
--enable-dsa-cache-layer-split
# after
--enable-dsa-cache-layer-split --enable-prefill-cp --cp-strategy interleave

Defensive patterns

Strategy: validation

Validate before calling

if args.get("enable_dsa_cache_layer_split"):
    ok = args.get("enable_prefill_cp") and args.get("cp_strategy") == "interleave"
    ok = ok or (args.get("enable_nsa_prefill_context_parallel") and args.get("nsa_prefill_cp_mode") == "round-robin-split")
    assert ok, "dsa-cache-layer-split requires prefill CP (interleave)"

Prevention

Group dependent flags into one named config bundle so prerequisites travel together
Add a preflight flag-consistency check for CP-related options

When it happens

Trigger: Passing --enable-dsa-cache-layer-split without --enable-prefill-cp, or with --cp-strategy set to something other than 'interleave'.

Common situations: Enabling the layer-split flag without its CP prerequisites; changing cp-strategy for a different optimization and breaking this one.

Related errors

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