{"record":{"id":"6ba5c6b60f1a1dc5","repo":"sgl-project/sglang","slug":"the-argument-disaggregation-decode-enable-offload-6ba5c6","errorCode":null,"errorMessage":"The argument disaggregation-decode-enable-offload-kvcache is only supported when hicache-storage-backend is provided.","messagePattern":"The argument disaggregation-decode-enable-offload-kvcache is only supported when hicache-storage-backend is provided\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/server_args.py","lineNumber":9146,"sourceCode":"        ):\n            raise ValueError(\n                \"--disaggregation-decode-retraction-backup=host_pool requires \"\n                \"--disable-priority-preemption when priority scheduling is enabled.\"\n            )\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:","sourceCodeStart":9128,"sourceCodeEnd":9164,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/server_args.py#L9128-L9164","documentation":"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.","triggerScenarios":"Launching a PD decode server with --disaggregation-decode-enable-offload-kvcache but no --hicache-storage-backend argument (hicache_storage_backend stays None).","commonSituations":"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.","solutions":["Add --hicache-storage-backend with a backend such as mooncake or file alongside the offload flag","Verify the backend service (e.g. mooncake store) is reachable and configured before relaunch","Remove --disaggregation-decode-enable-offload-kvcache if no persistent storage backend is intended"],"exampleFix":"# before\npython -m sglang.launch_server --disaggregation-mode decode --disaggregation-decode-enable-offload-kvcache ...\n# after\npython -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","handlingStrategy":"validation","validationCode":"def validate_offload_backend(offload: bool, hicache_backend: str | None):\n    if offload:\n        assert hicache_backend is not None, (\n            \"kv offload requires --hicache-storage-backend (e.g. mooncake)\"\n        )","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Treat --disaggregation-decode-enable-offload-kvcache and --hicache-storage-backend as an atomic pair in templates","Health-check the storage backend service before launching the decode server"],"tags":["sglang","pd-disaggregation","kv-offload","hicache","missing-backend"],"backgroundTag":"missing-required-flag","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}