vllm-project/vllm · error · ValueError

Unsupported sleep-mode backend '{name}'. Registered backends

Error message

Unsupported sleep-mode backend '{name}'. Registered backends: {available}.

What it means

Raised by SleepModeBackendFactory.get_backend_class when model_config.sleep_mode_backend names a backend that is not in the registry. The error lists the registered backend names (or <none>) so the valid choices are visible.

Source

Thrown at vllm/device_allocator/sleep_mode_backend.py:169

    @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]()

    @classmethod
    def create_backend(cls, model_config: ModelConfig) -> SleepModeBackend:
        """Instantiate the backend selected by ``model_config``."""
        name = model_config.sleep_mode_backend
        backend_cls = cls.get_backend_class(name)
        if not backend_cls.is_supported():
            raise ValueError(
                f"Sleep-mode backend '{name}' is not supported on this platform."
            )
        logger.info("Using sleep-mode backend: %s", name)
        return backend_cls()

View on GitHub (pinned to c794754062)

Solutions

Read the error's 'Registered backends' list and use one of those exact names.
Fix typos/whitespace/case in the sleep_mode_backend value.
If a third-party backend was intended, verify its package is installed and its vllm.general_plugins entry point loads without import errors.

Example fix

# before
--sleep-mode-backend kumem   # typo
# after
--sleep-mode-backend cumem

Defensive patterns

Strategy: validation

Validate before calling

from vllm.device_allocator.sleep_mode_backend import SleepModeBackendFactory

name = cfg.sleep_mode_backend
if name not in SleepModeBackendFactory._registry:
    raise SystemExit(
        f"unknown sleep-mode backend {name!r}; "
        f"valid: {sorted(SleepModeBackendFactory._registry)}")

Type guard

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

Try / catch

try:
    backend = SleepModeBackendFactory.create_backend(model_config)
except ValueError as e:
    if "Registered backends" in str(e):
        print(str(e)); suggest_valid_names_and_exit()
    raise

Prevention

Derive the backend name from SleepModeBackendFactory._registry (or the error listing) instead of hardcoding.
Add config-schema validation for sleep_mode_backend against known names in CI.

When it happens

Trigger: Setting the sleep-mode backend config to an unregistered or misspelled name (e.g. 'cumem ' with whitespace, 'Criu' vs 'criu'), or referencing a backend whose plugin entry point failed to load.

Common situations: Typos in config files; a plugin that should register the backend is not installed or its entry point is broken; the name exists only in a newer/older vLLM version.

Related errors

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