vllm-project/vllm · error · ValueError

Unrecognized distributed executor backend {self.distributed_

Error message

Unrecognized distributed executor backend {self.distributed_executor_backend}. Supported values are 'ray', 'mp' 'uni', 'external_launcher',  custom Executor subclass or its import path.

What it means

ParallelConfig validates that distributed_executor_backend, when not a string, must be a class that is a subclass of vLLM's Executor. Any other non-string object (an instance, an arbitrary class, a module) is rejected. String values (including import paths) are accepted here and validated later at import time.

Source

Thrown at vllm/config/parallel.py:1014

    @model_validator(mode="after")
    def _verify_args(self) -> Self:
        # Lazy import to avoid circular import
        from vllm.v1.executor import Executor

        # Enable batch invariance settings if requested
        if envs.VLLM_BATCH_INVARIANT:
            self.disable_custom_all_reduce = True

        if (
            self.distributed_executor_backend is not None
            and not isinstance(self.distributed_executor_backend, str)
            and not (
                isinstance(self.distributed_executor_backend, type)
                and issubclass(self.distributed_executor_backend, Executor)
            )
        ):
            raise ValueError(
                "Unrecognized distributed executor backend "
                f"{self.distributed_executor_backend}. Supported "
                "values are 'ray', 'mp' 'uni', 'external_launcher', "
                " custom Executor subclass or its import path."
            )
        if self.use_ray:
            from vllm.v1.executor import ray_utils

            ray_utils.assert_ray_available()

        if not current_platform.use_custom_allreduce():
            self.disable_custom_all_reduce = True
            logger.debug(
                "Disabled the custom all-reduce kernel because it is not "
                "supported on current platform."
            )
        if self.ray_workers_use_nsight and not self.use_ray:
            raise ValueError(

View on GitHub (pinned to c794754062)

Solutions

1. Pass the Executor subclass itself, not an instance: distributed_executor_backend=MyExecutor.
2. Or pass its import path string: distributed_executor_backend='my_pkg.my_executor.MyExecutor'.
3. Ensure the class actually subclasses vllm.v1.executor.executor.Executor if it is custom.
4. If a string was intended, confirm it is a str type (not a module object) so later import validation handles it.

Example fix

# before
from vllm.v1.executor.uniproc_executor import UniProcExecutor
llm = LLM(model=..., distributed_executor_backend=UniProcExecutor())

# after
llm = LLM(model=..., distributed_executor_backend=UniProcExecutor)

from typing import Any
from vllm.v1.executor.executor import Executor

def is_valid_executor_backend(v: Any) -> bool:
    return v is None or isinstance(v, str) or (
        isinstance(v, type) and issubclass(v, Executor)
    )

from vllm.v1.executor.executor import Executor

def is_executor_class(v) -> TypeGuard[type[Executor]]:
    return isinstance(v, type) and issubclass(v, Executor)

try:
    LLM(model=m, distributed_executor_backend=backend)
except ValueError as e:
    if "Unrecognized distributed executor backend" in str(e):
        # fall back to a known string backend
        LLM(model=m, distributed_executor_backend='mp')
    else:
        raise

When it happens

Trigger: Passing an instance of an Executor subclass instead of the class (e.g. RayGPUExecutor(...) instead of RayGPUExecutor), passing a non-Executor class, or passing an object like a module or function as distributed_executor_backend in LLM(..., distributed_executor_backend=...).

Common situations: Programmatic API users constructing LLM() with a custom executor class forget the parentheses semantics (instance vs class); typos that resolve to a non-class object; wrapping executors in factories returning instances.

Related errors

• expected str or QuantKey, got {type(v).__name__}
• tool response messages require a tool_call_id; use ChatMessa
• request `{request_id}` is already in flight
• engine-core client is closed: {message}
• generate request `{request_id}` has an empty prompt_token_id

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