sgl-project/sglang · error · ValueError

--disaggregation-decode-retraction-backup=host_pool does not

Error message

--disaggregation-decode-retraction-backup=host_pool does not support --dcp-size > 1.

What it means

ServerArgs._handle_cache_compatibility rejects --disaggregation-decode-retraction-backup=host_pool when --dcp-size > 1. The host-pool retraction backup implementation does not support decode-context-parallel (DCP) sharding across multiple decode groups, so it is limited to dcp_size == 1.

Source

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

                )
            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 "
                "--disable-priority-preemption when priority scheduling is enabled."
            )

        if cfg.enable_hierarchical_cache and cfg.disable_radix_cache:
            raise ValueError(
                "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."
            )

View on GitHub (pinned to 0132848349)

Solutions

Set --dcp-size 1 (or drop it) if host_pool retraction backup is required
Disable the retraction backup (use the default) if DCP > 1 is required for capacity/throughput
Track upstream releases; DCP support for host_pool backup may land later — re-test then

Example fix

# before
python -m sglang.launch_server --disaggregation-mode decode --dcp-size 2 --disaggregation-decode-retraction-backup host_pool ...
# after
python -m sglang.launch_server --disaggregation-mode decode --dcp-size 2 ...

Defensive patterns

Strategy: validation

Validate before calling

def validate_dcp(dcp_size: int, retraction_backup: str | None):
    if retraction_backup == "host_pool":
        assert dcp_size <= 1, "host_pool retraction backup requires --dcp-size 1"

Prevention

Document feature-compatibility matrix for decode-tier flags in your runbooks
Run server-arg dry validation (construct ServerArgs) in CI for every config template

When it happens

Trigger: Launching a PD decode server with both --disaggregation-decode-retraction-backup host_pool and --dcp-size 2 or greater (common when scaling long-context decode with decode context parallelism).

Common situations: Enabling DCP for long-context throughput on the decode tier while also enabling host-pool retraction backup; upgrading configs where DCP was newly added but the retraction flag remained; assuming all decode-side features compose.

Related errors

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