vllm-project/vllm · error · ValueError

Sleep-mode backend '{name}' is already registered.

Error message

Sleep-mode backend '{name}' is already registered.

What it means

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'.

Source

Thrown at vllm/device_allocator/sleep_mode_backend.py:156

        # an allocator-level sleep leaves them intact (no reinit needed on resume).
        return True


class SleepModeBackendFactory:
    """Registry and resolver for sleep-mode backends.

    Mirrors ``KVConnectorFactory``: lazy module/class registration and a
    built-in registry populated at import time. Third-party backends register
    the same way from a ``vllm.general_plugins`` entry point.
    """

    _registry: dict[str, Callable[[], type[SleepModeBackend]]] = {}

    @classmethod
    def register_backend(cls, name: str, module_path: str, class_name: str) -> None:
        """Register a backend with a lazy-loading module and class name."""
        if name in cls._registry:
            raise ValueError(f"Sleep-mode backend '{name}' is already registered.")

        def loader() -> type[SleepModeBackend]:
            module = importlib.import_module(module_path)
            return getattr(module, class_name)

        cls._registry[name] = loader

    @classmethod
    def get_backend_class(cls, name: str) -> type[SleepModeBackend]:
        """Resolve a registered backend class by name."""
        if name not in cls._registry:
            available = ", ".join(sorted(cls._registry)) or "<none>"
            raise ValueError(
                f"Unsupported sleep-mode backend '{name}'. "
                f"Registered backends: {available}."
            )
        return cls._registry[name]()

View on GitHub (pinned to c794754062)

Solutions

  1. Rename the plugin backend to a unique name (e.g. prefix it with the vendor name) before registering.
  2. Deduplicate plugin entry points so the same backend is registered only once.
  3. If overriding a built-in was intended, check for an explicit replacement API instead of re-registration.

Example fix

# before
SleepModeBackendFactory.register_backend("cumem", "my_plugin.mod", "MyBackend")
# after
SleepModeBackendFactory.register_backend("acme_cumem", "my_plugin.mod", "MyBackend")
Defensive patterns

Strategy: validation

Validate before calling

from vllm.device_allocator.sleep_mode_backend import SleepModeBackendFactory

def register_unique(name, module_path, class_name):
    if name in SleepModeBackendFactory._registry:
        return  # already registered; skip instead of raising
    SleepModeBackendFactory.register_backend(name, module_path, class_name)

Type guard

def can_register_backend(name: str) -> bool:
    from vllm.device_allocator.sleep_mode_backend import SleepModeBackendFactory
    return name not in SleepModeBackendFactory._registry

Try / catch

try:
    SleepModeBackendFactory.register_backend(name, mod, cls)
except ValueError as e:
    if "already registered" in str(e):
        log.warning("backend %s already present; skipping", name)
    else:
        raise

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of vllm-project/vllm@c794754062 (2026-08-14). Data as JSON: /api/errors/3ce2b1d486a9a5e5. Report an issue: GitHub.