{"record":{"id":"efc9a2041e063545","repo":"sgl-project/sglang","slug":"the-arguments-disaggregation-decode-enable-offload","errorCode":null,"errorMessage":"The arguments disaggregation-decode-enable-offload-kvcache and disaggregation-decode-retraction-backup=host_pool are mutually exclusive: both build a decode host pool.","messagePattern":"The arguments disaggregation-decode-enable-offload-kvcache and disaggregation-decode-retraction-backup=host_pool are mutually exclusive: both build a decode host pool\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/server_args.py","lineNumber":9150,"sourceCode":"            )\n\n        if cfg.enable_hierarchical_cache and cfg.disable_radix_cache:\n            raise ValueError(\n                \"The arguments enable-hierarchical-cache and disable-radix-cache are mutually exclusive \"\n                \"and cannot be used at the same time. Please use only one of them.\"\n            )\n\n        if cfg.disaggregation_decode_enable_offload_kvcache:\n            if cfg.disaggregation_mode != \"decode\":\n                raise ValueError(\n                    \"The argument disaggregation-decode-enable-offload-kvcache is only supported for decode side.\"\n                )\n            if cfg.hicache_storage_backend is None:\n                raise ValueError(\n                    \"The argument disaggregation-decode-enable-offload-kvcache is only supported when hicache-storage-backend is provided.\"\n                )\n            if cfg.disaggregation_decode_retraction_backup == \"host_pool\":\n                raise ValueError(\n                    \"The arguments disaggregation-decode-enable-offload-kvcache and \"\n                    \"disaggregation-decode-retraction-backup=host_pool are mutually exclusive: \"\n                    \"both build a decode host pool.\"\n                )\n\n        # Validate the effective ratio: model branches may declare a reset\n        # (e.g. Step3p forces 1.0 under hierarchical cache) that supersedes\n        # the user input before it ever takes effect.\n        if not (0 < self._resolved().swa_full_tokens_ratio <= 1.0):\n            raise ValueError(\"--swa-full-tokens-ratio should be in range (0, 1.0].\")\n\n    def _handle_deterministic_inference(self):\n        cfg = resolving_view(self)\n        if cfg.rl_on_policy_target is not None:\n            logger.warning(\n                \"Enable deterministic inference because of rl_on_policy_target.\"\n            )\n            self._declare(","sourceCodeStart":9132,"sourceCodeEnd":9168,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/server_args.py#L9132-L9168","documentation":"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.","triggerScenarios":"Launching a PD decode server with both --disaggregation-decode-enable-offload-kvcache and --disaggregation-decode-retraction-backup host_pool set at the same time.","commonSituations":"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.","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"],"exampleFix":"# before\npython -m sglang.launch_server --disaggregation-mode decode --disaggregation-decode-retraction-backup host_pool --disaggregation-decode-enable-offload-kvcache --hicache-storage-backend mooncake ...\n# after\npython -m sglang.launch_server --disaggregation-mode decode --disaggregation-decode-enable-offload-kvcache --hicache-storage-backend mooncake ...","handlingStrategy":"validation","validationCode":"def validate_pool_features(retraction_backup: str | None, offload: bool):\n    assert not (retraction_backup == \"host_pool\" and offload), (\n        \"host_pool retraction backup and kv offload are mutually exclusive\"\n    )","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["sglang","pd-disaggregation","retraction","kv-offload","mutually-exclusive"],"backgroundTag":"mutually-exclusive-flags","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}