{"record":{"id":"388c35e8fd9944be","repo":"vllm-project/vllm","slug":"currently-async-scheduling-is-only-supported-with","errorCode":null,"errorMessage":"Currently, async scheduling is only supported with EAGLE/MTP/Draft Model/NGram GPU/DSpark kind of speculative decoding","messagePattern":"Currently, async scheduling is only supported with EAGLE/MTP/Draft Model/NGram GPU/DSpark kind of speculative decoding","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/vllm.py","lineNumber":1170,"sourceCode":"\n        if self.scheduler_config.async_scheduling:\n            # Async scheduling explicitly enabled, hard fail any incompatibilities.\n            # Currently, async scheduling only support eagle speculative\n            # decoding.\n            if uses_rocm_deepep_ht_dbo:\n                raise ValueError(\n                    \"Async scheduling is not compatible with ROCm DeepEP \"\n                    \"high-throughput DBO. Please use --no-async-scheduling or \"\n                    \"select a different all2all backend.\"\n                )\n            if self.speculative_config is not None:\n                if (\n                    self.speculative_config.method not in get_args(EagleModelTypes)\n                    and self.speculative_config.method not in get_args(NgramGPUTypes)\n                    and self.speculative_config.method != \"draft_model\"\n                    and self.speculative_config.method != \"dspark\"\n                ):\n                    raise ValueError(\n                        \"Currently, async scheduling is only supported \"\n                        \"with EAGLE/MTP/Draft Model/NGram GPU/DSpark kind of \"\n                        \"speculative decoding\"\n                    )\n                if self.speculative_config.disable_padded_drafter_batch:\n                    raise ValueError(\n                        \"Async scheduling is not compatible with \"\n                        \"disable_padded_drafter_batch=True.\"\n                    )\n            if not executor_supports_async_sched:\n                raise ValueError(\n                    f\"`{executor_backend}` does not support async scheduling yet.\"\n                )\n        elif self.scheduler_config.async_scheduling is None:\n            # Enable async scheduling unless there is an incompatible option.\n            if (\n                self.model_config is not None\n                and self.model_config.runner_type == \"pooling\"","sourceCodeStart":1152,"sourceCodeEnd":1188,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/vllm.py#L1152-L1188","documentation":"vLLM's asynchronous scheduler currently only supports a fixed set of speculative decoding methods: EAGLE family (incl. MTP), NGRAM GPU variants, `draft_model`, and `dspark`. If async scheduling is explicitly enabled together with any other speculative method, config validation rejects it at startup.","triggerScenarios":"Launching with `--async-scheduling` plus a speculative config whose method is outside EagleModelTypes/NgramGPUTypes/draft_model/dspark (e.g. `med`, `ngram` CPU variant, or other lookahead methods).","commonSituations":"Users experimenting with newer or CPU-side spec-decode algorithms while keeping async scheduling on; upgrading vLLM where the accepted method list changed.","solutions":["Switch to a supported speculative method (e.g. `--speculative-config '{\"method\":\"eagle\",...}'`, `ngram` GPU variant, `draft_model`, or `dspark`).","Or disable async scheduling with `--no-async-scheduling` to keep the chosen spec-decode method.","Check the installed vLLM version's supported list via `vllm.speculative.speculative_config` (EagleModelTypes/NgramGPUTypes) before configuring."],"exampleFix":"# before\nvllm serve meta-llama/Llama-3.1-8B-Instruct \\\n  --async-scheduling \\\n  --speculative-config '{\"method\": \"med\", \"num_speculative_tokens\": 4}'\n\n# after\nvllm serve meta-llama/Llama-3.1-8B-Instruct \\\n  --async-scheduling \\\n  --speculative-config '{\"method\": \"eagle\", \"model\": \".../Llama-3.1-8B-Instruct-eagle\"}'","handlingStrategy":"validation","validationCode":"from typing import get_args\nfrom vllm.speculative import EagleModelTypes, NgramGPUTypes  # names per installed version\nok = {\"draft_model\", \"dspark\", *get_args(EagleModelTypes), *get_args(NgramGPUTypes)}\nif async_scheduling and spec_method not in ok:\n    async_scheduling = False","typeGuard":null,"tryCatchPattern":"try:\n    LLM(**args)\nexcept ValueError as e:\n    if \"only supported with EAGLE/MTP\" in str(e):\n        args[\"async_scheduling\"] = False  # retry once\n    else:\n        raise","preventionTips":["Pin the accepted spec-decode method list per vLLM version","Pre-validate speculative_config against the async-scheduling allowlist"],"tags":["async-scheduling","speculative-decoding","startup-config"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}