{"record":{"id":"747bbff7dec80e07","repo":"vllm-project/vllm","slug":"unsupported-speculative-method-self-method","errorCode":null,"errorMessage":"Unsupported speculative method: '{self.method}'","messagePattern":"Unsupported speculative method: '(.+?)'","errorType":"exception","errorClass":"NotImplementedError","httpStatus":null,"severity":"error","filePath":"vllm/config/speculative.py","lineNumber":979,"sourceCode":"                    self.method = \"mlp_speculator\"\n                elif self.draft_model_config.hf_config.model_type in get_args(\n                    MTPModelTypes\n                ):\n                    self.method = \"mtp\"\n                    if (\n                        self.num_speculative_tokens > 1\n                        and self.draft_model_config.hf_config.model_type\n                        not in (\"step3p5_mtp\", \"inkling_mtp\")\n                    ):\n                        logger.warning(\n                            \"Enabling num_speculative_tokens > 1 will run \"\n                            \"multiple times of forward on same MTP layer\"\n                            \",which may result in lower acceptance rate\"\n                        )\n                elif self.method == \"draft_model\":\n                    pass\n                else:\n                    raise NotImplementedError(\n                        f\"Unsupported speculative method: '{self.method}'\"\n                    )\n\n                if self.method in (\"eagle\", \"eagle3\"):\n                    # EAGLE drafts share the target's positional space; a\n                    # draft checkpoint with a smaller max_position_embeddings\n                    # than the target under-sizes its rotary cache (#48894).\n                    SpeculativeConfig._maybe_override_draft_max_position_embeddings(\n                        self.draft_model_config.hf_config,\n                        self.target_model_config.max_model_len,\n                    )\n\n                # Replace hf_config for EAGLE draft_model\n                if self.method in (\"eagle\", \"eagle3\", \"dflash\"):\n                    from vllm.transformers_utils.configs.eagle import EAGLEConfig\n                    from vllm.transformers_utils.configs.speculators import (\n                        SpeculatorsConfig,\n                    )","sourceCodeStart":961,"sourceCodeEnd":997,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/speculative.py#L961-L997","documentation":"Raised in the post-init validation of SpeculativeConfig when the 'method' field does not match any of the implemented speculative decoding branches (eagle, eagle3, mlp, ngram, suffix, dflash, dspark, draft_model, mtp/model_type-based paths, custom_class, etc.). The else-branch raises NotImplementedError because there is no worker/worker-part pair registered for the given string. It surfaces before model loading, at config resolution time.","triggerScenarios":"Passing speculative_config with a misspelled or unrecognized method (e.g. 'method': 'lookahead', 'deepeed', 'Egle', or a method name from an older/newer vLLM version). Using a method that exists in documentation for a different vLLM version than the installed one.","commonSituations":"Typos in the speculative_config JSON string; version drift (a method renamed or not yet released in the installed build); copy-pasting configs from blog posts targeting a different vLLM release.","solutions":["Check the spelling of 'method' against the supported list in vllm/config/speculative.py (e.g. 'ngram', 'eagle', 'eagle3', 'mlp', 'suffix', 'dflash', 'dspark', 'draft_model')","Upgrade or downgrade vLLM to the version whose speculative methods match your config","If you intended a custom drafter, use method='custom_class' and pass speculative_class instead of an ad-hoc method string"],"exampleFix":"# before\nspeculative_config={\"method\": \"eagel\", \"model\": \"...\"}\n# after\nspeculative_config={\"method\": \"eagle\", \"model\": \"...\"}","handlingStrategy":"validation","validationCode":"SUPPORTED = {\"ngram\", \"eagle\", \"eagle3\", \"mlp\", \"suffix\", \"dflash\", \"dspark\", \"draft_model\", \"mtp\", \"custom_class\"}\nif (m := spec_cfg.get(\"method\")) not in SUPPORTED:\n    raise ValueError(f\"unsupported speculative method {m!r}; pick one of {sorted(SUPPORTED)}\")","typeGuard":"def is_supported_method(method: str) -> bool:\n    import vllm.config.speculative as s  # or hardcode the set for your pinned version\n    return method in getattr(s, \"SUPPORTED_METHODS\", {\"ngram\", \"eagle\", \"eagle3\", \"suffix\", \"dspark\", \"dflash\", \"mtp\"})","tryCatchPattern":null,"preventionTips":["Validate the method string against the supported list for your pinned vLLM version before constructing the engine","Pin the vLLM version in deployments so method names cannot drift under you","Fail your config loader on unknown keys instead of forwarding them verbatim"],"tags":["speculative-decoding","config","not-implemented","method-dispatch"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}