{"record":{"id":"023468e2210cc6f9","repo":"vllm-project/vllm","slug":"num-speculative-tokens-was-provided-but-without-sp","errorCode":null,"errorMessage":"num_speculative_tokens was provided but without speculative model.","messagePattern":"num_speculative_tokens was provided but without speculative model\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/speculative.py","lineNumber":796,"sourceCode":"                    self.quantization = self.target_model_config.quantization\n            elif self.method in (\"ngram\", \"[ngram]\"):\n                self.model = \"ngram\"\n            elif self.method == \"ngram_gpu\":\n                self.model = \"ngram_gpu\"\n            elif self.method == \"suffix\":\n                self.model = \"suffix\"\n            elif self.method == \"extract_hidden_states\":\n                self.model = \"extract_hidden_states\"\n            elif self.method == \"custom_class\":\n                # method was set explicitly, but model should already contain the\n                # custom module path. If not, this is a configuration error.\n                if self.model is None:\n                    raise ValueError(\n                        \"method='custom_class' requires 'model' to contain the \"\n                        \"custom proposer module path (e.g., 'my_module.MyProposer').\"\n                    )\n            else:\n                raise ValueError(\n                    \"num_speculative_tokens was provided but without speculative model.\"\n                )\n\n        if self.method in (\"ngram\", \"[ngram]\"):\n            self.method = \"ngram\"\n\n        if self.method in (\"ngram\", \"ngram_gpu\"):\n            # Set default values if not provided\n            if self.prompt_lookup_min is None and self.prompt_lookup_max is None:\n                # TODO(woosuk): Tune these values. They are arbitrarily chosen.\n                self.prompt_lookup_min = 5\n                self.prompt_lookup_max = 5\n            elif self.prompt_lookup_min is None:\n                if self.prompt_lookup_max is None:\n                    raise ValueError(\n                        \"Either prompt_lookup_max or prompt_lookup_min must be \"\n                        \"provided when using the ngram method.\"\n                    )","sourceCodeStart":778,"sourceCodeEnd":814,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/speculative.py#L778-L814","documentation":"Catch-all in SpeculativeConfig init: num_speculative_tokens was provided, no draft model was given, and method did not match any known self-drafting method (mtp, dspark, ngram, ngram_gpu, suffix, extract_hidden_states, custom_class). There is nothing vLLM can derive a draft from, so it errors instead of enabling broken speculation.","triggerScenarios":"--num-speculative-tokens 3 without --speculative-model; method misspelled (e.g. 'ngam', 'MTP') so it falls into the else branch; passing num_speculative_tokens via env/config while the method field was never set to a valid value.","commonSituations":"Assuming num_speculative-tokens alone enables speculation; typos in method strings; config keys silently not parsed in older versions so method stays None/draft_model.","solutions":["Provide a draft: --speculative-model <draft checkpoint> (method defaults to draft_model)","Or set --speculative-method to a valid self-drafting method (mtp, ngram, ngram_gpu, suffix, extract_hidden_states, custom_class)","Check the method spelling against SpeculativeConfig docs/get_args"],"exampleFix":"# before\n--num-speculative-tokens 3\n\n# after\n--num-speculative-tokens 3 --speculative-method ngram\n# or\n--num-speculative-tokens 3 --speculative-model Qwen2.5-0.5B","handlingStrategy":"validation","validationCode":"SELF_DRAFTING = {'mtp', 'dspark', 'ngram', 'ngram_gpu', 'suffix', 'extract_hidden_states', 'custom_class'}\n\ndef speculation_resolvable(method: str | None, model: str | None, n: int | None) -> bool:\n    return n is None or model is not None or (method in SELF_DRAFTING)","typeGuard":"null","tryCatchPattern":"null","preventionTips":["Always set --speculative-model or a valid --speculative-method when enabling --num-speculative-tokens","Spell method values exactly; keep a whitelist in launch tooling"],"tags":["speculative-decoding","config","cli","api-misuse"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}