{"record":{"id":"054e7868153acf94","repo":"sgl-project/sglang","slug":"disaggregation-decode-retraction-backup-host-poo-054e78","errorCode":null,"errorMessage":"--disaggregation-decode-retraction-backup=host_pool is only supported on a PD decode server.","messagePattern":"--disaggregation-decode-retraction-backup=host_pool is only supported on a PD decode server\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/server_args.py","lineNumber":9112,"sourceCode":"                and explicit\n            )\n            if not supported and explicit:\n                logger.warning(\n                    \"Disabling SGLANG_OPT_FP8_WO_A_GEMM: requires DeepGEMM JIT \"\n                    \"and sm100+ (Blackwell), or explicit opt-in on sm90; \"\n                    \"detected sm%d.\",\n                    sm,\n                )\n            if not supported:\n                envs.SGLANG_OPT_FP8_WO_A_GEMM.set(False)\n\n    def _handle_cache_compatibility(self):\n        cfg = resolving_view(self)\n        if (\n            cfg.disaggregation_decode_retraction_backup == \"host_pool\"\n            and cfg.disaggregation_mode != \"decode\"\n        ):\n            raise ValueError(\n                \"--disaggregation-decode-retraction-backup=host_pool is only \"\n                \"supported on a PD decode server.\"\n            )\n        if (\n            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 \"","sourceCodeStart":9094,"sourceCodeEnd":9130,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/server_args.py#L9094-L9130","documentation":"ServerArgs._handle_cache_compatibility rejects --disaggregation-decode-retraction-backup=host_pool when disaggregation_mode is not 'decode'. The host-pool retraction backup allocates host memory to back up retracted requests and only makes sense on the decode side of a prefill-decode (PD) disaggregated deployment; prefill or null disaggregation modes have no decode retraction to back up.","triggerScenarios":"Passing --disaggregation-decode-retraction-backup host_pool together with --disaggregation-mode prefill, or omitting --disaggregation-mode entirely, in the same server launch.","commonSituations":"Copy-pasting the decode-server flag set onto prefill servers in a PD pair; enabling the flag on a monolithic (non-disaggregated) server while testing; typos in disaggregation-mode values falling back to the default non-decode mode.","solutions":["Only set --disaggregation-decode-retraction-backup host_pool on the decode server where --disaggregation-mode decode is set","Split flag sets per role (prefill vs decode) in your launch scripts/config management","Remove the flag if you are not running PD disaggregation at all"],"exampleFix":"# before (prefill server, wrong)\npython -m sglang.launch_server --disaggregation-mode prefill --disaggregation-decode-retraction-backup host_pool ...\n# after (prefill server)\npython -m sglang.launch_server --disaggregation-mode prefill ...","handlingStrategy":"validation","validationCode":"def validate_decode_flags(disaggregation_mode: str, retraction_backup: str | None):\n    if retraction_backup == \"host_pool\":\n        assert disaggregation_mode == \"decode\", (\n            \"host_pool retraction backup is decode-only\"\n        )","typeGuard":"def is_pd_decode_server(mode: str) -> bool:\n    return mode == \"decode\"\n","tryCatchPattern":"try:\n    ServerArgs(...)  # or launch\nexcept ValueError as e:\n    if \"only supported on a PD decode server\" in str(e):\n        raise SystemExit(f\"move host_pool flag to decode server: {e}\")\n    raise","preventionTips":["Generate prefill/decode flag sets from role-specific templates, never one shared list","Add a preflight assert: decode-only flags require disaggregation_mode == 'decode'"],"tags":["sglang","pd-disaggregation","retraction","host-pool","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"}