vllm-project/vllm · error · NotImplementedError

Unsupported speculative method: '{self.method}'

Error message

Unsupported speculative method: '{self.method}'

What it means

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.

Source

Thrown at vllm/config/speculative.py:979

                    self.method = "mlp_speculator"
                elif self.draft_model_config.hf_config.model_type in get_args(
                    MTPModelTypes
                ):
                    self.method = "mtp"
                    if (
                        self.num_speculative_tokens > 1
                        and self.draft_model_config.hf_config.model_type
                        not in ("step3p5_mtp", "inkling_mtp")
                    ):
                        logger.warning(
                            "Enabling num_speculative_tokens > 1 will run "
                            "multiple times of forward on same MTP layer"
                            ",which may result in lower acceptance rate"
                        )
                elif self.method == "draft_model":
                    pass
                else:
                    raise NotImplementedError(
                        f"Unsupported speculative method: '{self.method}'"
                    )

                if self.method in ("eagle", "eagle3"):
                    # EAGLE drafts share the target's positional space; a
                    # draft checkpoint with a smaller max_position_embeddings
                    # than the target under-sizes its rotary cache (#48894).
                    SpeculativeConfig._maybe_override_draft_max_position_embeddings(
                        self.draft_model_config.hf_config,
                        self.target_model_config.max_model_len,
                    )

                # Replace hf_config for EAGLE draft_model
                if self.method in ("eagle", "eagle3", "dflash"):
                    from vllm.transformers_utils.configs.eagle import EAGLEConfig
                    from vllm.transformers_utils.configs.speculators import (
                        SpeculatorsConfig,
                    )

View on GitHub (pinned to c794754062)

Solutions

1. 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')
2. Upgrade or downgrade vLLM to the version whose speculative methods match your config
3. If you intended a custom drafter, use method='custom_class' and pass speculative_class instead of an ad-hoc method string

Example fix

# before
speculative_config={"method": "eagel", "model": "..."}
# after
speculative_config={"method": "eagle", "model": "..."}

SUPPORTED = {"ngram", "eagle", "eagle3", "mlp", "suffix", "dflash", "dspark", "draft_model", "mtp", "custom_class"}
if (m := spec_cfg.get("method")) not in SUPPORTED:
    raise ValueError(f"unsupported speculative method {m!r}; pick one of {sorted(SUPPORTED)}")

def is_supported_method(method: str) -> bool:
    import vllm.config.speculative as s  # or hardcode the set for your pinned version
    return method in getattr(s, "SUPPORTED_METHODS", {"ngram", "eagle", "eagle3", "suffix", "dspark", "dflash", "mtp"})

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• rejection_sample_method='synthetic' requires exactly one of
• synthetic_acceptance_rates must have length {n}, got {rates}
• synthetic_acceptance_rates entries must be in [0, 1], got {r
• synthetic_acceptance_rates must be non-increasing, got {rate
• synthetic_acceptance_length must be in [1, {n + 1}], got {le

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