openai/whisper · error · ValueError

best_of with greedy sampling (T=0) is not compatible

Error message

best_of with greedy sampling (T=0) is not compatible

What it means

In _verify_options(): best_of means sampling N candidate sequences and picking the best by average log-probability, which requires stochastic sampling. With temperature=0 the sampler is greedy and deterministic, so drawing N candidates is meaningless and the combination is rejected.

Source

Thrown at whisper/decoding.py:577

        if not options.without_timestamps:
            precision = CHUNK_LENGTH / model.dims.n_audio_ctx  # usually 0.02 seconds
            max_initial_timestamp_index = None
            if options.max_initial_timestamp:
                max_initial_timestamp_index = round(
                    self.options.max_initial_timestamp / precision
                )
            self.logit_filters.append(
                ApplyTimestampRules(
                    tokenizer, self.sample_begin, max_initial_timestamp_index
                )
            )

    def _verify_options(self, options: DecodingOptions) -> DecodingOptions:
        if options.beam_size is not None and options.best_of is not None:
            raise ValueError("beam_size and best_of can't be given together")
        if options.temperature == 0:
            if options.best_of is not None:
                raise ValueError("best_of with greedy sampling (T=0) is not compatible")
        if options.patience is not None and options.beam_size is None:
            raise ValueError("patience requires beam_size to be given")
        if options.length_penalty is not None and not (
            0 <= options.length_penalty <= 1
        ):
            raise ValueError("length_penalty (alpha) should be a value between 0 and 1")

        return options

    def _get_initial_tokens(self) -> Tuple[int]:
        tokens = list(self.sot_sequence)

        if prefix := self.options.prefix:
            prefix_tokens = (
                self.tokenizer.encode(" " + prefix.strip())
                if isinstance(prefix, str)
                else prefix
            )

View on GitHub (pinned to 5f86d1d863)

Solutions

1. Set a non-zero temperature when using best_of: DecodingOptions(temperature=0.5, best_of=5)
2. If you want deterministic top-N, use beam search instead: beam_size=5, best_of=None
3. Remove best_of entirely for plain greedy decoding

Example fix

# before
options = whisper.DecodingOptions(best_of=5)  # temperature defaults to 0 -> ValueError

# after
options = whisper.DecodingOptions(temperature=0.7, best_of=5)
# or deterministic alternative:
# options = whisper.DecodingOptions(beam_size=5)

def best_of_ok(options) -> bool:
    return options.best_of is None or (options.temperature or 0) > 0

When it happens

Trigger: DecodingOptions(temperature=0, best_of=5) with beam_size=None; temperature defaults to 0 when constructing DecodingOptions, so merely setting best_of without touching temperature triggers it.

Common situations: Users assuming best_of works like 'top-N greedy'; default temperature sneaking in as 0; porting settings where temperature was previously non-zero.

Related errors

• beam_size and best_of can't be given together
• patience requires beam_size to be given
• length_penalty (alpha) should be a value between 0 and 1

AI-assisted analysis of openai/whisper@5f86d1d863 (2026-08-14). Data as JSON: /api/errors/43538142af210157. Report an issue: GitHub.