sgl-project/sglang · error · ValueError

The arguments disaggregation-decode-enable-offload-kvcache a

Error message

The arguments disaggregation-decode-enable-offload-kvcache and disaggregation-decode-retraction-backup=host_pool are mutually exclusive: both build a decode host pool.

What it means

ServerArgs validation rejects using --disaggregation-decode-enable-offload-kvcache together with --disaggregation-decode-retraction-backup=host_pool. Both features independently construct a decode-side host memory pool for KV data; enabling both would double-allocate host memory and conflict, so they are mutually exclusive.

Source

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

            )

        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:
            logger.warning(
                "Enable deterministic inference because of rl_on_policy_target."
            )
            self._declare(

View on GitHub (pinned to 0132848349)

Solutions

Choose one: keep --disaggregation-decode-retraction-backup host_pool and drop the offload flag, or vice versa
Prefer offload (with hicache backend) if persistent KV reuse matters; prefer host_pool backup if only retraction safety matters
Codify a lint check in deploy scripts that forbids both flags appearing together

Example fix

# before
python -m sglang.launch_server --disaggregation-mode decode --disaggregation-decode-retraction-backup host_pool --disaggregation-decode-enable-offload-kvcache --hicache-storage-backend mooncake ...
# after
python -m sglang.launch_server --disaggregation-mode decode --disaggregation-decode-enable-offload-kvcache --hicache-storage-backend mooncake ...

Defensive patterns

Strategy: validation

Validate before calling

def validate_pool_features(retraction_backup: str | None, offload: bool):
    assert not (retraction_backup == "host_pool" and offload), (
        "host_pool retraction backup and kv offload are mutually exclusive"
    )

Prevention

Pick exactly one decode host-pool strategy per deployment; document the choice
Add a config linter that rejects flag pairs known to be mutually exclusive before submit

When it happens

Trigger: Launching a PD decode server with both --disaggregation-decode-enable-offload-kvcache and --disaggregation-decode-retraction-backup host_pool set at the same time.

Common situations: Stacking decode resilience features (retraction backup + KV offload) assuming they compose; incrementally adding flags during tuning until validation fails; merging configs from two deployments that each used one of the features.

Related errors

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