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 when hicache-storage-backend is provided.

What it means

ServerArgs validation rejects --disaggregation-decode-enable-offload-kvcache when --hicache-storage-backend is not provided. The decode KV-cache offload feature writes evicted KV data through the hierarchical-cache storage layer, so it requires an explicit persistent storage backend (e.g. mooncake, file) to offload into.

Source

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

        ):
            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].")

    def _handle_deterministic_inference(self):
        cfg = resolving_view(self)
        if cfg.rl_on_policy_target is not None:

View on GitHub (pinned to 0132848349)

Solutions

1. Add --hicache-storage-backend with a backend such as mooncake or file alongside the offload flag
2. Verify the backend service (e.g. mooncake store) is reachable and configured before relaunch
3. Remove --disaggregation-decode-enable-offload-kvcache if no persistent storage backend is intended

Example fix

# before
python -m sglang.launch_server --disaggregation-mode decode --disaggregation-decode-enable-offload-kvcache ...
# after
python -m sglang.launch_server --disaggregation-mode decode --disaggregation-decode-enable-offload-kvcache --hicache-storage-backend mooncake --hicache-storage-backend-mooncake-config-path /etc/mooncake/config.json

def validate_offload_backend(offload: bool, hicache_backend: str | None):
    if offload:
        assert hicache_backend is not None, (
            "kv offload requires --hicache-storage-backend (e.g. mooncake)"
        )

When it happens

Trigger: Launching a PD decode server with --disaggregation-decode-enable-offload-kvcache but no --hicache-storage-backend argument (hicache_storage_backend stays None).

Common situations: Assuming host memory is enough and the offload works without a storage backend; forgetting the companion hicache flags when copying partial configs; backend flag renamed or omitted during upgrades.

Related errors

• The argument disaggregation-decode-enable-offload-kvcache is
• The arguments disaggregation-decode-enable-offload-kvcache a
• MiniCPM SALA does not support hierarchical cache
• MiniCPM sparse attention does not support PD disaggregation
• PD decode DCP requires --disaggregation-transfer-backend moo

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