{"record":{"id":"0307bd9aec826330","repo":"vllm-project/vllm","slug":"suffix-decoding-max-spec-factor-self-suffix-decod","errorCode":null,"errorMessage":"suffix_decoding_max_spec_factor={self.suffix_decoding_max_spec_factor} must be >= 0","messagePattern":"suffix_decoding_max_spec_factor=(.+?) must be >= 0","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/speculative.py","lineNumber":1172,"sourceCode":"            # dynamically and treats num_speculative_tokens as a maximum limit.\n            self.num_speculative_tokens = self.suffix_decoding_max_tree_depth\n            logger.warning(\n                \"Defaulted num_speculative_tokens to %s for suffix decoding.\",\n                self.num_speculative_tokens,\n            )\n        # Validate values\n        if self.suffix_decoding_max_tree_depth < 1:\n            raise ValueError(\n                f\"suffix_decoding_max_tree_depth=\"\n                f\"{self.suffix_decoding_max_tree_depth} must be >= 1\"\n            )\n        if self.suffix_decoding_max_cached_requests < 0:\n            raise ValueError(\n                f\"suffix_decoding_max_cached_requests=\"\n                f\"{self.suffix_decoding_max_cached_requests} must be >= 0\"\n            )\n        if self.suffix_decoding_max_spec_factor < 0:\n            raise ValueError(\n                f\"suffix_decoding_max_spec_factor=\"\n                f\"{self.suffix_decoding_max_spec_factor} must be >= 0\"\n            )\n        if not 0 <= self.suffix_decoding_min_token_prob <= 1:\n            raise ValueError(\n                f\"suffix_decoding_min_token_prob=\"\n                f\"{self.suffix_decoding_min_token_prob} must be in [0, 1]\"\n            )\n\n    @staticmethod\n    def _maybe_override_draft_max_model_len(\n        speculative_max_model_len: int | None,\n        draft_max_model_len: int,\n        target_max_model_len: int,\n    ) -> int:\n        \"\"\"Determine the max sequence len for the draft model. This is usually\n        the draft_max_model_len, but may be the target_max_model_len if it is\n        less than the draft_max_model_len, or may be speculative_max_model_len","sourceCodeStart":1154,"sourceCodeEnd":1190,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/speculative.py#L1154-L1190","documentation":"Raised by _validate_suffix_decoding when suffix_decoding_max_spec_factor < 0. This factor limits speculation length as a multiple of the prompt suffix match; a negative factor would forbid all speculation, so it is rejected. It must simply be non-negative.","triggerScenarios":"speculative_config={'method': 'suffix', 'suffix_decoding_max_spec_factor': -0.5} or any negative value; parameter sweeps that include 0/negative boundaries.","commonSituations":"Tuning the aggressiveness of suffix speculation and passing a negative number by mistake; sign confusion between 'factor' (multiplier) and 'limit' (subtraction).","solutions":["Set suffix_decoding_max_spec_factor to >= 0 (typical values around 4-10)","Remove the key to use the default"],"exampleFix":"# before\nspeculative_config={\"method\": \"suffix\", \"suffix_decoding_max_spec_factor\": -1}\n# after\nspeculative_config={\"method\": \"suffix\", \"suffix_decoding_max_spec_factor\": 6}","handlingStrategy":"validation","validationCode":"spec_cfg[\"suffix_decoding_max_spec_factor\"] = max(0.0, float(spec_cfg.get(\"suffix_decoding_max_spec_factor\", 6)))","typeGuard":"def is_valid_spec_factor(f: float) -> bool:\n    return f >= 0","tryCatchPattern":null,"preventionTips":["Remember the factor is a non-negative multiplier, not an offset","Validate swept parameters against their domains before launching engine instances"],"tags":["speculative-decoding","suffix-decoding","range-validation","config"],"backgroundTag":null,"analyzedSha":"c794754062d49a8fdb63ab3c5215b488b865030c","analyzedAt":"2026-08-14T21:17:39.825Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}