sgl-project/sglang · error · ValueError

--radix-cache-backend={name!r} is not registered. Registered

Error message

--radix-cache-backend={name!r} is not registered. Registered backends: {registered_radix_cache_backends()}. External backends must call register_radix_cache_backend(...) at import time.

What it means

create_tree_cache raises ValueError when --radix-cache-backend names a backend that was never registered via register_radix_cache_backend(...). The registry only knows factories registered at import time, so late/dynamic registration or typos fail here with the list of valid names.

Source

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

    cache = UnifiedRadixCache(params)
    if (
        ctx.enable_hierarchical_cache
        or get_disagg().disaggregation_decode_retraction_backup == "host_pool"
    ):
        cache.init_hicache(server_args, params)
        ctx.tp_worker.register_hicache_layer_transfer_counter(
            cache.cache_controller.layer_done_counter
        )
    return cache


def create_tree_cache(ctx: TreeCacheBuildContext) -> BasePrefixCache:
    """Route to the matching factory to construct Radix Cache."""
    name = ctx.server_args.radix_cache_backend
    if name:
        factory = get_radix_cache_factory(name)
        if factory is None:
            raise ValueError(
                f"--radix-cache-backend={name!r} is not registered. "
                f"Registered backends: {registered_radix_cache_backends()}. "
                "External backends must call register_radix_cache_backend(...) at import time."
            )
        cache = factory(ctx)
        source = f"registered({name!r})"
    else:
        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(

View on GitHub (pinned to 0132848349)

Solutions

Import the module that calls register_radix_cache_backend(...) before create_tree_cache runs (e.g. via --chat-template style plugin import or patching entry point)
Check the error message's registered list and fix typos in the flag value
Verify the plugin is installed in the server's Python environment (pip list / import in the same venv)

Example fix

# before
# my_plugin.py never imported; server started with --radix-cache-backend mycache
# after
# in my_plugin.py (imported at startup):
from sglang.srt.mem_cache.registry import register_radix_cache_backend
register_radix_cache_backend("mycache", my_factory)

Defensive patterns

Strategy: validation

Validate before calling

from sglang.srt.mem_cache.registry import registered_radix_cache_backends
name = server_args.radix_cache_backend
if name and name not in registered_radix_cache_backends():
    raise ValueError(f"backend {name!r} unknown; known: {registered_radix_cache_backends()}")

Prevention

Import plugin modules that call register_radix_cache_backend before server start
Validate backend names against the registry in CI config tests

When it happens

Trigger: Launching with --radix-cache-backend mycache where 'mycache' was never registered (typo, module not imported, or registration attempted after server start instead of at import time).

Common situations: Custom out-of-tree radix cache plugins whose module isn't imported by the server process; renaming a backend across versions; copy-pasting a backend name from docs that doesn't match the installed version.

Related errors

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