sgl-project/sglang · error · ValueError

The arguments enable-hierarchical-cache and…

Error message

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.

What it means

ServerArgs._handle_cache_compatibility rejects using --enable-hierarchical-cache and --disable-radix-cache together. Hierarchical cache (HiCache) is built on top of the radix cache; disabling radix cache removes the structure HiCache layers on top of it, so the two flags are mutually exclusive and only one may be set.

Solutions

If you want hierarchical/offload caching, remove --disable-radix-cache
If you truly need radix cache disabled, remove --enable-hierarchical-cache (and any hicache options)
If you only wanted to flush prefix cache between tests, restart the server or use the flush API instead of --disable-radix-cache

Example fix

# before
python -m sglang.launch_server --model ... --enable-hierarchical-cache --hicache-storage-backend mooncake --disable-radix-cache
# after
python -m sglang.launch_server --model ... --enable-hierarchical-cache --hicache-storage-backend mooncake

Defensive patterns

Strategy: validation

Validate before calling

def validate_cache_flags(enable_hierarchical_cache: bool, disable_radix_cache: bool):
    assert not (enable_hierarchical_cache and disable_radix_cache), (
        "enable-hierarchical-cache and disable-radix-cache are mutually exclusive"
    )

Prevention

Remember HiCache builds on the radix tree: disabling radix cache disables HiCache
Use the cache-flush HTTP API for test isolation instead of --disable-radix-cache

When it happens

Trigger: Passing both --enable-hierarchical-cache and --disable-radix-cache in the same server launch (e.g. to offload KV to storage while also trying to turn off prefix caching).

Common situations: Trying to combine KV-cache offload with prefix-cache disable for benchmark isolation; migrating configs where --disable-radix-cache was a workaround for prefix-cache bugs; misunderstanding that HiCache requires the radix tree.

Understand the failure class

Background: "mutually exclusive" flag errors: what "can't supply both nx and xx", "--raw is not compatible with -i" and "cannot be used with" mean, and how to fix them — this error's family across 29 libraries.

Related errors

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

Appendix: source

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

            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."
                )
            if cfg.disaggregation_decode_retraction_backup == "host_pool":
                raise ValueError(
                    "The arguments disaggregation-decode-enable-offload-kvcache and "
                    "disaggregation-decode-retraction-backup=host_pool are mutually exclusive: "
                    "both build a decode host pool."

View on GitHub (pinned to 0132848349)