openai/whisper · error · ValueError

length_penalty (alpha) should be a value between 0 and 1

Error message

length_penalty (alpha) should be a value between 0 and 1

What it means

_verify_options() constrains length_penalty (the alpha exponent applied to beam sequence length, per the original Whisper paper: ((5+len)/6)^alpha) to the inclusive range [0, 1]. Values outside that range distort the log-probability normalization in ways the implementation does not support, so they are rejected up front.

Source

Thrown at whisper/decoding.py:583

                )
            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
            )
            if self.sample_len is not None:
                max_prefix_len = self.n_ctx // 2 - self.sample_len
                prefix_tokens = prefix_tokens[-max_prefix_len:]
            tokens = tokens + prefix_tokens

        if prompt := self.options.prompt:

View on GitHub (pinned to 5f86d1d863)

Solutions

1. Clamp the value into [0, 1] (note the check is inclusive, so 0 and 1 are valid)
2. Leave length_penalty=None to use the default behavior
3. Fix the config source that produced the out-of-range number

Example fix

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

# after
options = whisper.DecodingOptions(beam_size=5, length_penalty=1.0)  # or omit / clamp: max(0.0, min(1.0, lp))

def length_penalty_ok(options) -> bool:
    lp = options.length_penalty
    return lp is None or 0 <= lp <= 1

When it happens

Trigger: DecodingOptions(length_penalty=-0.1) or length_penalty=1.2 with beam_size set; floats arriving from CLI/config parsing where 0 and 1 boundaries were misread as exclusive.

Common situations: Tuning scripts sweeping penalties beyond the valid range; porting alpha from another seq2seq toolkit where values >1 are legal; YAML configs parsed as strings then float()ed into wrong magnitudes.

Related errors

• beam_size and best_of can't be given together
• patience requires beam_size to be given
• 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/794ed8a0a2329b5d. Report an issue: GitHub.