{"record":{"id":"787fdcf9f66dc2eb","repo":"sgl-project/sglang","slug":"radix-cache-backend-name-r-is-not-registered","errorCode":null,"errorMessage":"--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.","messagePattern":"--radix-cache-backend=(.+?) is not registered\\. Registered backends: (.+?)\\. External backends must call register_radix_cache_backend\\(\\.\\.\\.\\) at import time\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/sglang/srt/mem_cache/registry.py","lineNumber":205,"sourceCode":"    cache = UnifiedRadixCache(params)\n    if (\n        ctx.enable_hierarchical_cache\n        or get_disagg().disaggregation_decode_retraction_backup == \"host_pool\"\n    ):\n        cache.init_hicache(server_args, params)\n        ctx.tp_worker.register_hicache_layer_transfer_counter(\n            cache.cache_controller.layer_done_counter\n        )\n    return cache\n\n\ndef create_tree_cache(ctx: TreeCacheBuildContext) -> BasePrefixCache:\n    \"\"\"Route to the matching factory to construct Radix Cache.\"\"\"\n    name = ctx.server_args.radix_cache_backend\n    if name:\n        factory = get_radix_cache_factory(name)\n        if factory is None:\n            raise ValueError(\n                f\"--radix-cache-backend={name!r} is not registered. \"\n                f\"Registered backends: {registered_radix_cache_backends()}. \"\n                \"External backends must call register_radix_cache_backend(...) at import time.\"\n            )\n        cache = factory(ctx)\n        source = f\"registered({name!r})\"\n    else:\n        cache = default_radix_cache_factory(ctx)\n        source = \"default\"\n\n    if (\n        get_memory().enable_hierarchical_cache\n        and ctx.server_args.hicache_host_memory_mode == \"buffer_only\"\n    ):\n        from sglang.srt.mem_cache.unified_radix_cache import UnifiedRadixCache\n\n        if not isinstance(cache, UnifiedRadixCache):\n            raise ValueError(","sourceCodeStart":187,"sourceCodeEnd":223,"githubUrl":"https://github.com/sgl-project/sglang/blob/0132848349585cfe6aae51c4941cbae872505f8a/python/sglang/srt/mem_cache/registry.py#L187-L223","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","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)"],"exampleFix":"# before\n# my_plugin.py never imported; server started with --radix-cache-backend mycache\n# after\n# in my_plugin.py (imported at startup):\nfrom sglang.srt.mem_cache.registry import register_radix_cache_backend\nregister_radix_cache_backend(\"mycache\", my_factory)","handlingStrategy":"validation","validationCode":"from sglang.srt.mem_cache.registry import registered_radix_cache_backends\nname = server_args.radix_cache_backend\nif name and name not in registered_radix_cache_backends():\n    raise ValueError(f\"backend {name!r} unknown; known: {registered_radix_cache_backends()}\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Import plugin modules that call register_radix_cache_backend before server start","Validate backend names against the registry in CI config tests"],"tags":["radix-cache","backend-registry","plugin","server-args","value-error"],"backgroundTag":"unregistered-plugin-backend","analyzedSha":"0132848349585cfe6aae51c4941cbae872505f8a","analyzedAt":"2026-08-28T05:10:05.995Z","schemaVersion":2},"datasetVersion":"2026-08-28T06:17:29.519Z"}