{"record":{"id":"928c3a9f79c2d3e1","repo":"sgl-project/sglang","slug":"disaggregation-decode-enable-radix-cache-is-inco-928c3a","errorCode":null,"errorMessage":"--disaggregation-decode-enable-radix-cache is incompatible with speculative decoding (--speculative-algorithm {})","messagePattern":"--disaggregation-decode-enable-radix-cache is incompatible with speculative decoding \\(--speculative-algorithm (.+?)\\)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/arg_groups/pd_disaggregation_hook.py","lineNumber":87,"sourceCode":"            raise ValueError(\n                \"PD decode DCP currently requires chunk cache; \"\n                \"--enable-hierarchical-cache is not supported.\"\n            )\n\n    if cfg.disaggregation_mode == \"decode\":\n        if cfg.disaggregation_decode_enable_radix_cache:\n            if cfg.enable_hisparse:\n                raise ValueError(\n                    \"--disaggregation-decode-enable-radix-cache is incompatible \"\n                    \"with --enable-hisparse\"\n                )\n            if cfg.disaggregation_transfer_backend == \"fake\":\n                raise ValueError(\n                    \"--disaggregation-decode-enable-radix-cache is incompatible \"\n                    \"with --disaggregation-transfer-backend fake\"\n                )\n            if cfg.speculative_algorithm is not None:\n                raise ValueError(\n                    \"--disaggregation-decode-enable-radix-cache is incompatible \"\n                    \"with speculative decoding \"\n                    f\"(--speculative-algorithm {cfg.speculative_algorithm})\"\n                )\n            from sglang.srt.arg_groups.overrides import resolved_view\n\n            if resolved_view(server_args).enable_dp_attention:\n                logger.warning(\n                    \"EXPERIMENTAL: Decode radix cache with DP attention. \"\n                    \"Requires prefix-aware DP rank routing for optimal cache hits.\"\n                )\n            declare_resolution(\n                server_args,\n                \"handle_pd_disaggregation\",\n                disable_radix_cache=False,\n            )\n            logger.warning(\"EXPERIMENTAL: Radix cache is enabled for decode server\")\n        else:","sourceCodeStart":69,"sourceCodeEnd":105,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/arg_groups/pd_disaggregation_hook.py#L69-L105","documentation":"Decode-side radix cache in PD disaggregation is incompatible with speculative decoding: prefill happens on a different node, so draft-model KV needed by EAGLE/NEXTN-style speculation cannot be populated by the decode-side radix cache.","triggerScenarios":"--disaggregation-mode decode with --disaggregation-decode-enable-radix-cache and any --speculative-algorithm set (EAGLE, EAGLE3, NEXTN, ...).","commonSituations":"Enabling prefix caching on decode nodes of a disaggregated deployment that also serves with speculative decoding.","solutions":["Remove --disaggregation-decode-enable-radix-cache when using speculative decoding in decode mode","Or disable speculative decoding if decode radix cache matters more"],"exampleFix":"# before\n--disaggregation-mode decode --disaggregation-decode-enable-radix-cache --speculative-algorithm EAGLE\n# after\n--disaggregation-mode decode --speculative-algorithm EAGLE","handlingStrategy":"validation","validationCode":"if cfg.disaggregation_mode == \"decode\" and cfg.disaggregation_decode_enable_radix_cache:\n    assert cfg.speculative_algorithm is None","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Remember speculation needs prefill-side draft KV; decode radix cache cannot provide it in PD setups"],"tags":["sglang","pd-disaggregation","radix-cache","speculative-decoding","config-conflict"],"backgroundTag":"feature-incompatibility","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}