{"record":{"id":"f66609f46b95fee7","repo":"openai/whisper","slug":"beam-size-and-best-of-can-t-be-given-together","errorCode":null,"errorMessage":"beam_size and best_of can't be given together","messagePattern":"beam_size and best_of can't be given together","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"whisper/decoding.py","lineNumber":574,"sourceCode":"            self.logit_filters.append(SuppressBlank(self.tokenizer, self.sample_begin))\n        if self.options.suppress_tokens:\n            self.logit_filters.append(SuppressTokens(self._get_suppress_tokens()))\n        if not options.without_timestamps:\n            precision = CHUNK_LENGTH / model.dims.n_audio_ctx  # usually 0.02 seconds\n            max_initial_timestamp_index = None\n            if options.max_initial_timestamp:\n                max_initial_timestamp_index = round(\n                    self.options.max_initial_timestamp / precision\n                )\n            self.logit_filters.append(\n                ApplyTimestampRules(\n                    tokenizer, self.sample_begin, max_initial_timestamp_index\n                )\n            )\n\n    def _verify_options(self, options: DecodingOptions) -> DecodingOptions:\n        if options.beam_size is not None and options.best_of is not None:\n            raise ValueError(\"beam_size and best_of can't be given together\")\n        if options.temperature == 0:\n            if options.best_of is not None:\n                raise ValueError(\"best_of with greedy sampling (T=0) is not compatible\")\n        if options.patience is not None and options.beam_size is None:\n            raise ValueError(\"patience requires beam_size to be given\")\n        if options.length_penalty is not None and not (\n            0 <= options.length_penalty <= 1\n        ):\n            raise ValueError(\"length_penalty (alpha) should be a value between 0 and 1\")\n\n        return options\n\n    def _get_initial_tokens(self) -> Tuple[int]:\n        tokens = list(self.sot_sequence)\n\n        if prefix := self.options.prefix:\n            prefix_tokens = (\n                self.tokenizer.encode(\" \" + prefix.strip())","sourceCodeStart":556,"sourceCodeEnd":592,"githubUrl":"https://github.com/openai/whisper/blob/5f86d1d86363843179951550570367b37c5d6f78/whisper/decoding.py#L556-L592","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pick one strategy: keep beam_size for deterministic beam search, drop best_of","If you wanted sampling with N candidates, keep best_of and set beam_size=None (and temperature > 0 — see the T=0 check)","Read back whisper.decoding.DecodingOptions defaults so you only override what you intend"],"exampleFix":"# before\noptions = whisper.DecodingOptions(beam_size=5, best_of=5)  # ValueError\n\n# after\noptions = whisper.DecodingOptions(beam_size=5)\n# or sampling-based:\n# options = whisper.DecodingOptions(temperature=0.8, best_of=5)","handlingStrategy":"validation","validationCode":"def valid_options(o) -> bool:\n    return not (o.beam_size is not None and o.best_of is not None)","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set exactly one of beam_size / best_of in option dicts; make the other key absent, not None-toggled","Keep decoding configs in one place and unit-test them by constructing DecodingTask once at startup"],"tags":["decoding","options-validation","beam-search"],"backgroundTag":null,"analyzedSha":"5f86d1d86363843179951550570367b37c5d6f78","analyzedAt":"2026-08-14T18:53:59.547Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}