{"record":{"id":"3ce2b1d486a9a5e5","repo":"vllm-project/vllm","slug":"sleep-mode-backend-name-is-already-registered","errorCode":null,"errorMessage":"Sleep-mode backend '{name}' is already registered.","messagePattern":"Sleep-mode backend '(.+?)' is already registered\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/device_allocator/sleep_mode_backend.py","lineNumber":156,"sourceCode":"        # an allocator-level sleep leaves them intact (no reinit needed on resume).\n        return True\n\n\nclass SleepModeBackendFactory:\n    \"\"\"Registry and resolver for sleep-mode backends.\n\n    Mirrors ``KVConnectorFactory``: lazy module/class registration and a\n    built-in registry populated at import time. Third-party backends register\n    the same way from a ``vllm.general_plugins`` entry point.\n    \"\"\"\n\n    _registry: dict[str, Callable[[], type[SleepModeBackend]]] = {}\n\n    @classmethod\n    def register_backend(cls, name: str, module_path: str, class_name: str) -> None:\n        \"\"\"Register a backend with a lazy-loading module and class name.\"\"\"\n        if name in cls._registry:\n            raise ValueError(f\"Sleep-mode backend '{name}' is already registered.\")\n\n        def loader() -> type[SleepModeBackend]:\n            module = importlib.import_module(module_path)\n            return getattr(module, class_name)\n\n        cls._registry[name] = loader\n\n    @classmethod\n    def get_backend_class(cls, name: str) -> type[SleepModeBackend]:\n        \"\"\"Resolve a registered backend class by name.\"\"\"\n        if name not in cls._registry:\n            available = \", \".join(sorted(cls._registry)) or \"<none>\"\n            raise ValueError(\n                f\"Unsupported sleep-mode backend '{name}'. \"\n                f\"Registered backends: {available}.\"\n            )\n        return cls._registry[name]()\n","sourceCodeStart":138,"sourceCodeEnd":174,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/device_allocator/sleep_mode_backend.py#L138-L174","documentation":"Raised by SleepModeBackendFactory.register_backend when a sleep-mode backend name is registered twice. The factory keeps a lazy name->loader registry (mirroring KVConnectorFactory) and refuses duplicate names to avoid silently shadowing a built-in backend like 'cumem'.","triggerScenarios":"A plugin calls SleepModeBackendFactory.register_backend(\"cumem\", ...) (or any name already registered) after vLLM already registered the built-ins at import time; typically a vllm.general_plugins entry point that collides with a built-in name.","commonSituations":"A third-party sleep-mode plugin chooses a name that matches a built-in; registering the same plugin twice via two entry points; upgrading vLLM adds a built-in that now collides with a previously private plugin name.","solutions":["Rename the plugin backend to a unique name (e.g. prefix it with the vendor name) before registering.","Deduplicate plugin entry points so the same backend is registered only once.","If overriding a built-in was intended, check for an explicit replacement API instead of re-registration."],"exampleFix":"# before\nSleepModeBackendFactory.register_backend(\"cumem\", \"my_plugin.mod\", \"MyBackend\")\n# after\nSleepModeBackendFactory.register_backend(\"acme_cumem\", \"my_plugin.mod\", \"MyBackend\")","handlingStrategy":"validation","validationCode":"from vllm.device_allocator.sleep_mode_backend import SleepModeBackendFactory\n\ndef register_unique(name, module_path, class_name):\n    if name in SleepModeBackendFactory._registry:\n        return  # already registered; skip instead of raising\n    SleepModeBackendFactory.register_backend(name, module_path, class_name)","typeGuard":"def can_register_backend(name: str) -> bool:\n    from vllm.device_allocator.sleep_mode_backend import SleepModeBackendFactory\n    return name not in SleepModeBackendFactory._registry","tryCatchPattern":"try:\n    SleepModeBackendFactory.register_backend(name, mod, cls)\nexcept ValueError as e:\n    if \"already registered\" in str(e):\n        log.warning(\"backend %s already present; skipping\", name)\n    else:\n        raise","preventionTips":["Namespace third-party backend names with a vendor prefix.","Register plugins idempotently: check the registry before calling register_backend.","Have plugin entry points log their name at load so collisions are traceable."],"tags":["vllm","sleep-mode","plugin","registry","duplicate"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}