{"record":{"id":"547176ea10d26eac","repo":"vllm-project/vllm","slug":"suffix-decoding-max-tree-depth-self-suffix-decodi","errorCode":null,"errorMessage":"suffix_decoding_max_tree_depth={self.suffix_decoding_max_tree_depth} must be >= 1","messagePattern":"suffix_decoding_max_tree_depth=(.+?) must be >= 1","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"vllm/config/speculative.py","lineNumber":1162,"sourceCode":"        return self\n\n    def _validate_suffix_decoding(self):\n        if not has_arctic_inference():\n            raise ImportError(\n                \"Arctic Inference is required for suffix decoding. \"\n                \"Install via `pip install arctic-inference==0.1.1`.\"\n            )\n        if self.num_speculative_tokens is None:\n            # Suffix decoding decides the actual number of speculative tokens\n            # 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            )","sourceCodeStart":1144,"sourceCodeEnd":1180,"githubUrl":"https://github.com/vllm-project/vllm/blob/c794754062d49a8fdb63ab3c5215b488b865030c/vllm/config/speculative.py#L1144-L1180","documentation":"Raised by _validate_suffix_decoding when suffix_decoding_max_tree_depth < 1. The tree depth bounds how deep the suffix-automaton draft tree grows per step; zero or negative depth yields an empty speculation tree, so it is rejected. Note when num_speculative_tokens is unset it is defaulted to this depth, which also makes a 0 value degenerate.","triggerScenarios":"speculative_config={'method': 'suffix', 'suffix_decoding_max_tree_depth': 0} or a negative value; env-driven config templating that zero-initializes tuning knobs.","commonSituations":"Disabling the feature by setting it to 0 instead of removing it; sweeping tuning parameters and passing 0 as the low end of the sweep.","solutions":["Set suffix_decoding_max_tree_depth to >= 1 (typical values are 4-64 depending on workload)","Remove the key to use the default depth"],"exampleFix":"# before\nspeculative_config={\"method\": \"suffix\", \"suffix_decoding_max_tree_depth\": 0}\n# after\nspeculative_config={\"method\": \"suffix\", \"suffix_decoding_max_tree_depth\": 16}","handlingStrategy":"validation","validationCode":"if spec_cfg.get(\"method\") == \"suffix\":\n    assert (d := spec_cfg.get(\"suffix_decoding_max_tree_depth\", 16)) >= 1, \"tree depth must be >= 1\"","typeGuard":"def is_valid_tree_depth(depth: int) -> bool:\n    return depth >= 1","tryCatchPattern":null,"preventionTips":["Never use 0 to disable suffix decoding — remove the method instead","Clamp tuning sweeps for suffix knobs to their documented domains before feeding them to the engine"],"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"}