openai/whisper · error · ValueError

beam_size and best_of can't be given together

Error message

beam_size and best_of can't be given together

What it means

DecodingOptions validation in DecodingTask._verify_options(): beam search (beam_size) and nucleus fallback sampling (best_of) are two alternative candidate-generation strategies and are mutually exclusive. Supplying both is a configuration error caught before decoding starts.

Source

Thrown at whisper/decoding.py:574

            self.logit_filters.append(SuppressBlank(self.tokenizer, self.sample_begin))
        if self.options.suppress_tokens:
            self.logit_filters.append(SuppressTokens(self._get_suppress_tokens()))
        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())

View on GitHub (pinned to 5f86d1d863)

Solutions

1. Pick one strategy: keep beam_size for deterministic beam search, drop best_of
2. If you wanted sampling with N candidates, keep best_of and set beam_size=None (and temperature > 0 — see the T=0 check)
3. Read back whisper.decoding.DecodingOptions defaults so you only override what you intend

Example fix

# before
options = whisper.DecodingOptions(beam_size=5, best_of=5)  # ValueError

# after
options = whisper.DecodingOptions(beam_size=5)
# or sampling-based:
# options = whisper.DecodingOptions(temperature=0.8, best_of=5)

def valid_options(o) -> bool:
    return not (o.beam_size is not None and o.best_of is not None)

When it happens

Trigger: Constructing DecodingOptions(beam_size=5, best_of=5) and running DecodingTask/whisper.decode; passing both through transcribe()'s internally built options is not possible (transcribe only exposes temperature), so this is hit via the lower-level whisper.decoding API.

Common situations: Copy-pasting options from examples that mix beam search and sampling params; porting configs from other toolkits (e.g. fairseq) where num_hypotheses + sampling coexist; interactive tuning scripts that set every knob.

Related errors

• patience requires beam_size to be given
• length_penalty (alpha) should be a value between 0 and 1
• best_of with greedy sampling (T=0) is not compatible

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