sgl-project/sglang · error · ValueError

--disaggregation-decode-retraction-backup=host_pool requires

Error message

--disaggregation-decode-retraction-backup=host_pool requires --disable-priority-preemption when priority scheduling is enabled.

What it means

ServerArgs._handle_cache_compatibility rejects the combination of --disaggregation-decode-retraction-backup=host_pool with priority scheduling enabled (--enable-priority-scheduling) unless --disable-priority-preemption is also set. The host-pool retraction backup path is incompatible with priority preemption's request-retraction mechanics, so priority scheduling is only allowed in non-preempting mode when the backup pool is on.

Source

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

        ):
            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."
            )

        if cfg.disaggregation_decode_enable_offload_kvcache:
            if cfg.disaggregation_mode != "decode":
                raise ValueError(
                    "The argument disaggregation-decode-enable-offload-kvcache is only supported for decode side."
                )
            if cfg.hicache_storage_backend is None:
                raise ValueError(
                    "The argument disaggregation-decode-enable-offload-kvcache is only supported when hicache-storage-backend is provided."

View on GitHub (pinned to 0132848349)

Solutions

1. Add --disable-priority-preemption alongside --enable-priority-scheduling and the host_pool backup flag
2. Or drop --disaggregation-decode-retraction-backup host_pool if priority preemption matters more than host-backed retraction
3. Or disable priority scheduling entirely if neither override is acceptable

Example fix

# before
python -m sglang.launch_server --disaggregation-mode decode --disaggregation-decode-retraction-backup host_pool --enable-priority-scheduling ...
# after
python -m sglang.launch_server --disaggregation-mode decode --disaggregation-decode-retraction-backup host_pool --enable-priority-scheduling --disable-priority-preemption ...

def validate_priority(retraction_backup: str | None, enable_priority: bool, disable_preemption: bool):
    if retraction_backup == "host_pool" and enable_priority:
        assert disable_preemption, "add --disable-priority-preemption"

When it happens

Trigger: Launching with --disaggregation-decode-retraction-backup host_pool and --enable-priority-scheduling without --disable-priority-preemption on a PD decode server.

Common situations: Enabling priority scheduling for SLO-tiered serving and host-pool backup together on the decode tier; importing a full flag list from another deployment that had preemption disabled; not realizing priority preemption is on by default when priority scheduling is enabled.

Related errors

• --disaggregation-decode-retraction-backup=host_pool is only
• --disaggregation-decode-retraction-backup=host_pool does not
• The arguments disaggregation-decode-enable-offload-kvcache a
• MiniCPM sparse attention does not support PD disaggregation
• PD decode DCP requires --disaggregation-transfer-backend moo

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