sgl-project/sglang · error · ValueError

--disaggregation-decode-retraction-backup=host_pool is only

Error message

--disaggregation-decode-retraction-backup=host_pool is only supported on a PD decode server.

What it means

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.

Source

Thrown at python/sglang/srt/server_args.py:9112

                and explicit
            )
            if not supported and explicit:
                logger.warning(
                    "Disabling SGLANG_OPT_FP8_WO_A_GEMM: requires DeepGEMM JIT "
                    "and sm100+ (Blackwell), or explicit opt-in on sm90; "
                    "detected sm%d.",
                    sm,
                )
            if not supported:
                envs.SGLANG_OPT_FP8_WO_A_GEMM.set(False)

    def _handle_cache_compatibility(self):
        cfg = resolving_view(self)
        if (
            cfg.disaggregation_decode_retraction_backup == "host_pool"
            and cfg.disaggregation_mode != "decode"
        ):
            raise ValueError(
                "--disaggregation-decode-retraction-backup=host_pool is only "
                "supported on a PD decode server."
            )
        if (
            cfg.disaggregation_decode_retraction_backup == "host_pool"
            and cfg.dcp_size > 1
        ):
            raise ValueError(
                "--disaggregation-decode-retraction-backup=host_pool does not "
                "support --dcp-size > 1."
            )
        if (
            cfg.disaggregation_decode_retraction_backup == "host_pool"
            and cfg.enable_priority_scheduling
            and not cfg.disable_priority_preemption
        ):
            raise ValueError(
                "--disaggregation-decode-retraction-backup=host_pool requires "

View on GitHub (pinned to 0132848349)

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

Example fix

# before (prefill server, wrong)
python -m sglang.launch_server --disaggregation-mode prefill --disaggregation-decode-retraction-backup host_pool ...
# after (prefill server)
python -m sglang.launch_server --disaggregation-mode prefill ...

Defensive patterns

Strategy: validation

Validate before calling

def validate_decode_flags(disaggregation_mode: str, retraction_backup: str | None):
    if retraction_backup == "host_pool":
        assert disaggregation_mode == "decode", (
            "host_pool retraction backup is decode-only"
        )

Type guard

def is_pd_decode_server(mode: str) -> bool:
    return mode == "decode"

Try / catch

try:
    ServerArgs(...)  # or launch
except ValueError as e:
    if "only supported on a PD decode server" in str(e):
        raise SystemExit(f"move host_pool flag to decode server: {e}")
    raise

Prevention

Generate prefill/decode flag sets from role-specific templates, never one shared list
Add a preflight assert: decode-only flags require disaggregation_mode == 'decode'

When it happens

Trigger: Passing --disaggregation-decode-retraction-backup host_pool together with --disaggregation-mode prefill, or omitting --disaggregation-mode entirely, in the same server launch.

Common situations: 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.

Related errors

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/054e7868153acf94. Report an issue: GitHub.