{"record":{"id":"6a92ec2daaedeb8e","repo":"vllm-project/vllm","slug":"unrecognized-distributed-executor-backend-self-di","errorCode":null,"errorMessage":"Unrecognized distributed executor backend {self.distributed_executor_backend}. Supported values are 'ray', 'mp' 'uni', 'external_launcher',  custom Executor subclass or its import path.","messagePattern":"Unrecognized distributed executor backend (.+?)\\. Supported values are 'ray', 'mp' 'uni', 'external_launcher',  custom Executor subclass or its import path\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/parallel.py","lineNumber":1014,"sourceCode":"\n    @model_validator(mode=\"after\")\n    def _verify_args(self) -> Self:\n        # Lazy import to avoid circular import\n        from vllm.v1.executor import Executor\n\n        # Enable batch invariance settings if requested\n        if envs.VLLM_BATCH_INVARIANT:\n            self.disable_custom_all_reduce = True\n\n        if (\n            self.distributed_executor_backend is not None\n            and not isinstance(self.distributed_executor_backend, str)\n            and not (\n                isinstance(self.distributed_executor_backend, type)\n                and issubclass(self.distributed_executor_backend, Executor)\n            )\n        ):\n            raise ValueError(\n                \"Unrecognized distributed executor backend \"\n                f\"{self.distributed_executor_backend}. Supported \"\n                \"values are 'ray', 'mp' 'uni', 'external_launcher', \"\n                \" custom Executor subclass or its import path.\"\n            )\n        if self.use_ray:\n            from vllm.v1.executor import ray_utils\n\n            ray_utils.assert_ray_available()\n\n        if not current_platform.use_custom_allreduce():\n            self.disable_custom_all_reduce = True\n            logger.debug(\n                \"Disabled the custom all-reduce kernel because it is not \"\n                \"supported on current platform.\"\n            )\n        if self.ray_workers_use_nsight and not self.use_ray:\n            raise ValueError(","sourceCodeStart":996,"sourceCodeEnd":1032,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/parallel.py#L996-L1032","documentation":"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.","triggerScenarios":"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=...).","commonSituations":"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.","solutions":["Pass the Executor subclass itself, not an instance: distributed_executor_backend=MyExecutor.","Or pass its import path string: distributed_executor_backend='my_pkg.my_executor.MyExecutor'.","Ensure the class actually subclasses vllm.v1.executor.executor.Executor if it is custom.","If a string was intended, confirm it is a str type (not a module object) so later import validation handles it."],"exampleFix":"# before\nfrom vllm.v1.executor.uniproc_executor import UniProcExecutor\nllm = LLM(model=..., distributed_executor_backend=UniProcExecutor())\n\n# after\nllm = LLM(model=..., distributed_executor_backend=UniProcExecutor)","handlingStrategy":"type-guard","validationCode":"from typing import Any\nfrom vllm.v1.executor.executor import Executor\n\ndef is_valid_executor_backend(v: Any) -> bool:\n    return v is None or isinstance(v, str) or (\n        isinstance(v, type) and issubclass(v, Executor)\n    )","typeGuard":"from vllm.v1.executor.executor import Executor\n\ndef is_executor_class(v) -> TypeGuard[type[Executor]]:\n    return isinstance(v, type) and issubclass(v, Executor)","tryCatchPattern":"try:\n    LLM(model=m, distributed_executor_backend=backend)\nexcept ValueError as e:\n    if \"Unrecognized distributed executor backend\" in str(e):\n        # fall back to a known string backend\n        LLM(model=m, distributed_executor_backend='mp')\n    else:\n        raise","preventionTips":["Pass Executor subclasses by class, never instance.","Prefer the import-path string form for custom executors in serialized configs."],"tags":["parallelism","executor","type-validation","api-misuse"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}