{"record":{"id":"df83cb8640d3903c","repo":"sgl-project/sglang","slug":"the-arguments-enable-hierarchical-cache-and-disabl","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/server_args.py","lineNumber":9135,"sourceCode":"            cfg.disaggregation_decode_retraction_backup == \"host_pool\"\n            and cfg.dcp_size > 1\n        ):\n            raise ValueError(\n                \"--disaggregation-decode-retraction-backup=host_pool does not \"\n                \"support --dcp-size > 1.\"\n            )\n        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.\"","sourceCodeStart":9117,"sourceCodeEnd":9153,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/server_args.py#L9117-L9153","documentation":"ServerArgs._handle_cache_compatibility rejects using --enable-hierarchical-cache and --disable-radix-cache together. Hierarchical cache (HiCache) is built on top of the radix cache; disabling radix cache removes the structure HiCache layers on top of it, so the two flags are mutually exclusive and only one may be set.","triggerScenarios":"Passing both --enable-hierarchical-cache and --disable-radix-cache in the same server launch (e.g. to offload KV to storage while also trying to turn off prefix caching).","commonSituations":"Trying to combine KV-cache offload with prefix-cache disable for benchmark isolation; migrating configs where --disable-radix-cache was a workaround for prefix-cache bugs; misunderstanding that HiCache requires the radix tree.","solutions":["If you want hierarchical/offload caching, remove --disable-radix-cache","If you truly need radix cache disabled, remove --enable-hierarchical-cache (and any hicache options)","If you only wanted to flush prefix cache between tests, restart the server or use the flush API instead of --disable-radix-cache"],"exampleFix":"# before\npython -m sglang.launch_server --model ... --enable-hierarchical-cache --hicache-storage-backend mooncake --disable-radix-cache\n# after\npython -m sglang.launch_server --model ... --enable-hierarchical-cache --hicache-storage-backend mooncake","handlingStrategy":"validation","validationCode":"def validate_cache_flags(enable_hierarchical_cache: bool, disable_radix_cache: bool):\n    assert not (enable_hierarchical_cache and disable_radix_cache), (\n        \"enable-hierarchical-cache and disable-radix-cache are mutually exclusive\"\n    )","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Remember HiCache builds on the radix tree: disabling radix cache disables HiCache","Use the cache-flush HTTP API for test isolation instead of --disable-radix-cache"],"tags":["sglang","hicache","radix-cache","mutually-exclusive","config-validation"],"backgroundTag":"mutually-exclusive-flags","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}