vllm-project/vllm · error · ValueError

suffix_decoding_max_spec_factor={self.suffix_decoding_max_sp

Error message

suffix_decoding_max_spec_factor={self.suffix_decoding_max_spec_factor} must be >= 0

What it means

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.

Source

Thrown at vllm/config/speculative.py:1172

            # dynamically and treats num_speculative_tokens as a maximum limit.
            self.num_speculative_tokens = self.suffix_decoding_max_tree_depth
            logger.warning(
                "Defaulted num_speculative_tokens to %s for suffix decoding.",
                self.num_speculative_tokens,
            )
        # Validate values
        if self.suffix_decoding_max_tree_depth < 1:
            raise ValueError(
                f"suffix_decoding_max_tree_depth="
                f"{self.suffix_decoding_max_tree_depth} must be >= 1"
            )
        if self.suffix_decoding_max_cached_requests < 0:
            raise ValueError(
                f"suffix_decoding_max_cached_requests="
                f"{self.suffix_decoding_max_cached_requests} must be >= 0"
            )
        if self.suffix_decoding_max_spec_factor < 0:
            raise ValueError(
                f"suffix_decoding_max_spec_factor="
                f"{self.suffix_decoding_max_spec_factor} must be >= 0"
            )
        if not 0 <= self.suffix_decoding_min_token_prob <= 1:
            raise ValueError(
                f"suffix_decoding_min_token_prob="
                f"{self.suffix_decoding_min_token_prob} must be in [0, 1]"
            )

    @staticmethod
    def _maybe_override_draft_max_model_len(
        speculative_max_model_len: int | None,
        draft_max_model_len: int,
        target_max_model_len: int,
    ) -> int:
        """Determine the max sequence len for the draft model. This is usually
        the draft_max_model_len, but may be the target_max_model_len if it is
        less than the draft_max_model_len, or may be speculative_max_model_len

View on GitHub (pinned to c794754062)

Solutions

1. Set suffix_decoding_max_spec_factor to >= 0 (typical values around 4-10)
2. Remove the key to use the default

Example fix

# before
speculative_config={"method": "suffix", "suffix_decoding_max_spec_factor": -1}
# after
speculative_config={"method": "suffix", "suffix_decoding_max_spec_factor": 6}

spec_cfg["suffix_decoding_max_spec_factor"] = max(0.0, float(spec_cfg.get("suffix_decoding_max_spec_factor", 6)))

def is_valid_spec_factor(f: float) -> bool:
    return f >= 0

When it happens

Trigger: speculative_config={'method': 'suffix', 'suffix_decoding_max_spec_factor': -0.5} or any negative value; parameter sweeps that include 0/negative boundaries.

Common situations: Tuning the aggressiveness of suffix speculation and passing a negative number by mistake; sign confusion between 'factor' (multiplier) and 'limit' (subtraction).

Related errors

• suffix_decoding_max_tree_depth={self.suffix_decoding_max_tre
• suffix_decoding_max_cached_requests={self.suffix_decoding_ma
• suffix_decoding_min_token_prob={self.suffix_decoding_min_tok
• rejection_sample_method='synthetic' requires exactly one of
• synthetic_acceptance_rates must have length {n}, got {rates}

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