sgl-project/sglang · error · ValueError

The argument disaggregation-decode-enable-offload-kvcache is

Error message

The argument disaggregation-decode-enable-offload-kvcache is only supported for decode side.

What it means

ServerArgs validation rejects --disaggregation-decode-enable-offload-kvcache when the server is not a PD decode server (disaggregation_mode != 'decode'). KV-cache offload on retraction is a decode-side mechanism that pushes evicted/retracted KV tensors to host storage; prefill servers and monolithic servers have no such offload path.

Source

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

        if (
            cfg.disaggregation_decode_retraction_backup == "host_pool"
            and cfg.enable_priority_scheduling
            and not cfg.disable_priority_preemption
        ):
            raise ValueError(
                "--disaggregation-decode-retraction-backup=host_pool requires "
                "--disable-priority-preemption when priority scheduling is enabled."
            )

        if cfg.enable_hierarchical_cache and cfg.disable_radix_cache:
            raise ValueError(
                "The arguments enable-hierarchical-cache and disable-radix-cache are mutually exclusive "
                "and cannot be used at the same time. Please use only one of them."
            )

        if cfg.disaggregation_decode_enable_offload_kvcache:
            if cfg.disaggregation_mode != "decode":
                raise ValueError(
                    "The argument disaggregation-decode-enable-offload-kvcache is only supported for decode side."
                )
            if cfg.hicache_storage_backend is None:
                raise ValueError(
                    "The argument disaggregation-decode-enable-offload-kvcache is only supported when hicache-storage-backend is provided."
                )
            if cfg.disaggregation_decode_retraction_backup == "host_pool":
                raise ValueError(
                    "The arguments disaggregation-decode-enable-offload-kvcache and "
                    "disaggregation-decode-retraction-backup=host_pool are mutually exclusive: "
                    "both build a decode host pool."
                )

        # Validate the effective ratio: model branches may declare a reset
        # (e.g. Step3p forces 1.0 under hierarchical cache) that supersedes
        # the user input before it ever takes effect.
        if not (0 < self._resolved().swa_full_tokens_ratio <= 1.0):
            raise ValueError("--swa-full-tokens-ratio should be in range (0, 1.0].")

View on GitHub (pinned to 0132848349)

Solutions

1. Move --disaggregation-decode-enable-offload-kvcache to the decode server only, with --disaggregation-mode decode
2. Remove the flag if running a non-disaggregated or prefill deployment
3. Maintain role-specific flag sets for prefill and decode launches

Example fix

# before (prefill server)
python -m sglang.launch_server --disaggregation-mode prefill --disaggregation-decode-enable-offload-kvcache ...
# after (decode server only)
python -m sglang.launch_server --disaggregation-mode decode --disaggregation-decode-enable-offload-kvcache --hicache-storage-backend mooncake ...

def validate_offload(disaggregation_mode: str, offload: bool):
    if offload:
        assert disaggregation_mode == "decode", (
            "kv offload flag is decode-only"
        )

def is_decode_server(mode: str) -> bool:
    return mode == "decode"

try:
    ServerArgs(...)
except ValueError as e:
    if "only supported for decode side" in str(e):
        # strip decode-only flags and retry on prefill/monolithic servers
        ...
    raise

When it happens

Trigger: Passing --disaggregation-decode-enable-offload-kvcache with --disaggregation-mode prefill, or with no disaggregation mode set at all.

Common situations: Applying the decode-tier flag list to the prefill side of a PD pair by mistake; enabling the flag while testing a monolithic server; automation templates that inject decode-only flags everywhere.

Related errors

• PD decode DCP requires --disaggregation-transfer-backend moo
• SGLANG_DISAGG_STAGING_BUFFER requires disaggregation_transfe
• --disaggregation-decode-retraction-backup=host_pool is only
• The argument disaggregation-decode-enable-offload-kvcache is
• The arguments disaggregation-decode-enable-offload-kvcache a

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