sgl-project/sglang · error · ValueError

--enable-session-radix-cache requires UnifiedRadixCache, but

Error message

--enable-session-radix-cache requires UnifiedRadixCache, but tree_cache is {type(cache).__name__}. Drop the flag or the option that selected another tree cache for this model.

What it means

create_tree_cache rejects --enable-session-radix-cache when the constructed tree cache lacks the enable_session_radix_cache attribute (i.e. is not UnifiedRadixCache). Session-scoped radix caching is implemented only on the unified cache, so other backends cannot honor the flag.

Source

Thrown at python/sglang/srt/mem_cache/registry.py:231

        cache = default_radix_cache_factory(ctx)
        source = "default"

    if (
        get_memory().enable_hierarchical_cache
        and ctx.server_args.hicache_host_memory_mode == "buffer_only"
    ):
        from sglang.srt.mem_cache.unified_radix_cache import UnifiedRadixCache

        if not isinstance(cache, UnifiedRadixCache):
            raise ValueError(
                "--hicache-host-memory-mode buffer_only is only implemented for "
                f"the unified radix tree; this model selected {type(cache).__name__}."
            )

    if ctx.server_args.enable_session_radix_cache and not getattr(
        cache, "enable_session_radix_cache", False
    ):
        raise ValueError(
            "--enable-session-radix-cache requires UnifiedRadixCache, but "
            f"tree_cache is {type(cache).__name__}. Drop the flag or the "
            "option that selected another tree cache for this model."
        )

    hicache_attached = cache.cache_controller is not None
    streaming_wrapped = False
    if (
        ctx.server_args.enable_streaming_session
        and not cache.supports_streaming_session()
    ):
        from sglang.srt.session.streaming_session import StreamingSession

        cache = StreamingSession(cache)
        streaming_wrapped = True

    logger.info(
        "Tree cache initialized: source=%s impl=%s hybrid_swa=%s hybrid_ssm=%s "

View on GitHub (pinned to 0132848349)

Solutions

1. Remove --enable-session-radix-cache, or remove the flag/setting that selected the non-unified tree cache
2. Use the default (unified) radix cache to keep session semantics
3. Extend a custom backend with an enable_session_radix_cache capability if you must keep it

Example fix

# before
--enable-session-radix-cache --radix-cache-backend cpp
# after
--enable-session-radix-cache

if server_args.enable_session_radix_cache:
    assert server_args.radix_cache_backend in (None, ""), "session radix cache needs unified tree"

When it happens

Trigger: Launching with --enable-session-radix-cache while another option (backend selection or model-specific factory) yields a non-unified cache class.

Common situations: Enabling per-session cache isolation for privacy in a deployment that also selects the C++ radix backend or a custom registered cache.

Related errors

• --hicache-host-memory-mode buffer_only is only implemented f
• Host-pool retraction does not support Mamba models.
• Host-pool retraction does not support pure-SWA models.
• --radix-cache-backend={name!r} is not registered. Registered
• MiniMax-H3 on MPS requires synchronous layerwise offload for

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