{"record":{"id":"6db1e3abbbad895b","repo":"sgl-project/sglang","slug":"the-argument-disaggregation-decode-enable-offload","errorCode":null,"errorMessage":"The argument disaggregation-decode-enable-offload-kvcache is only supported for decode side.","messagePattern":"The argument disaggregation-decode-enable-offload-kvcache is only supported for decode side\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/server_args.py","lineNumber":9142,"sourceCode":"        if (\n            cfg.disaggregation_decode_retraction_backup == \"host_pool\"\n            and cfg.enable_priority_scheduling\n            and not cfg.disable_priority_preemption\n        ):\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].\")","sourceCodeStart":9124,"sourceCodeEnd":9160,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/server_args.py#L9124-L9160","documentation":"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.","triggerScenarios":"Passing --disaggregation-decode-enable-offload-kvcache with --disaggregation-mode prefill, or with no disaggregation mode set at all.","commonSituations":"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.","solutions":["Move --disaggregation-decode-enable-offload-kvcache to the decode server only, with --disaggregation-mode decode","Remove the flag if running a non-disaggregated or prefill deployment","Maintain role-specific flag sets for prefill and decode launches"],"exampleFix":"# before (prefill server)\npython -m sglang.launch_server --disaggregation-mode prefill --disaggregation-decode-enable-offload-kvcache ...\n# after (decode server only)\npython -m sglang.launch_server --disaggregation-mode decode --disaggregation-decode-enable-offload-kvcache --hicache-storage-backend mooncake ...","handlingStrategy":"validation","validationCode":"def validate_offload(disaggregation_mode: str, offload: bool):\n    if offload:\n        assert disaggregation_mode == \"decode\", (\n            \"kv offload flag is decode-only\"\n        )","typeGuard":"def is_decode_server(mode: str) -> bool:\n    return mode == \"decode\"\n","tryCatchPattern":"try:\n    ServerArgs(...)\nexcept ValueError as e:\n    if \"only supported for decode side\" in str(e):\n        # strip decode-only flags and retry on prefill/monolithic servers\n        ...\n    raise","preventionTips":["Namespace flags by role in config files: [prefill], [decode] sections","Never propagate the full decode flag list to prefill nodes"],"tags":["sglang","pd-disaggregation","kv-offload","decode-only","config-validation"],"backgroundTag":"invalid-cli-config-combination","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}