vllm-project/vllm · error · ValueError

`{executor_backend}` does not support async scheduling yet.

Error message

`{executor_backend}` does not support async scheduling yet.

What it means

Each executor backend (the process/messaging layer that hosts workers) must opt in to async scheduling via `executor_class.supports_async_scheduling()`. If the chosen `--distributed-executor-backend` does not, explicitly enabling async scheduling fails validation with the backend name in the message.

Source

Thrown at vllm/config/vllm.py:1181

            if self.speculative_config is not None:
                if (
                    self.speculative_config.method not in get_args(EagleModelTypes)
                    and self.speculative_config.method not in get_args(NgramGPUTypes)
                    and self.speculative_config.method != "draft_model"
                    and self.speculative_config.method != "dspark"
                ):
                    raise ValueError(
                        "Currently, async scheduling is only supported "
                        "with EAGLE/MTP/Draft Model/NGram GPU/DSpark kind of "
                        "speculative decoding"
                    )
                if self.speculative_config.disable_padded_drafter_batch:
                    raise ValueError(
                        "Async scheduling is not compatible with "
                        "disable_padded_drafter_batch=True."
                    )
            if not executor_supports_async_sched:
                raise ValueError(
                    f"`{executor_backend}` does not support async scheduling yet."
                )
        elif self.scheduler_config.async_scheduling is None:
            # Enable async scheduling unless there is an incompatible option.
            if (
                self.model_config is not None
                and self.model_config.runner_type == "pooling"
            ):
                # The current implementation of asynchronous scheduling negatively
                # impacts performance of pooling models, so we disable by default.
                logger.debug(
                    "Disabling asynchronous scheduling by default for pooling model."
                )
                self.scheduler_config.async_scheduling = False
            elif (
                self.speculative_config is not None
                and self.speculative_config.method not in get_args(EagleModelTypes)
                and self.speculative_config.method not in get_args(NgramGPUTypes)

View on GitHub (pinned to c794754062)

Solutions

  1. Remove `--async-scheduling` (or pass `--no-async-scheduling`) for this executor backend.
  2. Or switch to an executor backend that supports async scheduling (e.g. `--distributed-executor-backend mp` / ray where supported in your vLLM version).
  3. If using a custom executor, implement `supports_async_scheduling()` returning True only after verifying compatibility.

Example fix

# before
vllm serve model --distributed-executor-backend external_launcher \
  --async-scheduling

# after
vllm serve model --distributed-executor-backend external_launcher \
  --no-async-scheduling
Defensive patterns

Strategy: validation

Validate before calling

from vllm.v1.executor import executor_class_from_backend  # per version
cls = executor_class_from_backend(backend)
if async_scheduling and not cls.supports_async_scheduling():
    async_scheduling = False

Try / catch

try:
    AsyncLLM.from_engine_args(args)
except ValueError as e:
    if "does not support async scheduling" in str(e):
        args.async_scheduling = False
    else:
        raise

Prevention

When it happens

Trigger: Launching with `--async-scheduling` and an executor backend whose class does not advertise support (e.g. some external/legacy multiprocess executors).

Common situations: Switching executor backends (e.g. to an older or external- launcher setup) while keeping `--async-scheduling` in a shared launch script; using custom executor plugins that never implemented the async-scheduling handshake.

Related errors

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