huggingface/transformers · error · ValueError

frame_length ({frame_length}) may not be larger than fft_len

Error message

frame_length ({frame_length}) may not be larger than fft_length ({fft_length})

What it means

Thrown by `spectrogram` when `frame_length > fft_length` (fft_length defaults to frame_length when None). The STFT pads each frame to fft_length before the FFT; a frame longer than the FFT buffer would truncate data, so the invariant frame_length <= fft_length is enforced up front.

Source

Thrown at src/transformers/audio_utils.py:933

            peak value and the smallest value will never be more than 80 dB. Must be greater than zero.
        remove_dc_offset (`bool`, *optional*):
            Subtract mean from waveform on each frame, applied before pre-emphasis. This should be set to `true` in
            order to get the same results as `torchaudio.compliance.kaldi.fbank` when computing mel filters.
        dtype (`np.dtype`, *optional*, defaults to `np.float32`):
            Data type of the spectrogram tensor. If `power` is None, this argument is ignored and the dtype will be
            `np.complex64`.

    Returns:
        `nd.array` containing a spectrogram of shape `(num_frequency_bins, length)` for a regular spectrogram or shape
        `(num_mel_filters, length)` for a mel spectrogram.
    """
    window_length = len(window)

    if fft_length is None:
        fft_length = frame_length

    if frame_length > fft_length:
        raise ValueError(f"frame_length ({frame_length}) may not be larger than fft_length ({fft_length})")

    if window_length != frame_length:
        raise ValueError(f"Length of the window ({window_length}) must equal frame_length ({frame_length})")

    if hop_length <= 0:
        raise ValueError("hop_length must be greater than zero")

    if waveform.ndim != 1:
        raise ValueError(f"Input waveform must have only one dimension, shape is {waveform.shape}")

    if np.iscomplexobj(waveform):
        raise ValueError("Complex-valued input waveforms are not currently supported")

    if power is None and mel_filters is not None:
        raise ValueError(
            "You have provided `mel_filters` but `power` is `None`. Mel spectrogram computation is not yet supported for complex-valued spectrogram."
            "Specify `power` to fix this issue."
        )

View on GitHub (pinned to a597f97485)

Solutions

1. Set fft_length >= frame_length (commonly fft_length == frame_length or the next power of two)
2. If fft_length was meant to be derived, use `next_power_of_two(frame_length)` from the same module
3. Re-check the processor config so frame_length and fft_length agree

Example fix

// before
spec = spectrogram(waveform, window, frame_length=512, hop_length=128, fft_length=400)  # ValueError

// after
spec = spectrogram(waveform, window, frame_length=400, hop_length=128, fft_length=512)

fft_length = fft_length or frame_length
assert frame_length <= fft_length, f"frame_length ({frame_length}) must be <= fft_length ({fft_length})"
spec = spectrogram(waveform, window, frame_length, hop_length, fft_length=fft_length)

def frame_fits_fft(frame_length: int, fft_length) -> bool:
    return fft_length is None or frame_length <= fft_length

try:
    spec = spectrogram(waveform, window, frame_length, hop_length, fft_length=fft_length)
except ValueError as e:
    if "may not be larger than fft_length" in str(e):
        spec = spectrogram(waveform, window, frame_length, hop_length, fft_length=frame_length)
    else:
        raise

When it happens

Trigger: Calling `spectrogram(waveform, window, frame_length=512, hop_length=..., fft_length=400)`. Also hit when a feature extractor computes fft_length independently (e.g. as the next power of two of a smaller value) while frame_length stays large.

Common situations: Configs where n_fft was lowered but frame_length not updated; porting from toolkits where fft_length is inferred differently; manually tuning hop/frame/fft parameters of a Whisper-style feature extractor.

Related errors

• Unknown window function '{name}'
• Length of the window ({window_length}) may not be larger tha
• Length of the window ({window_length}) must equal frame_leng
• hop_length must be greater than zero
• mel_scale should be one of "htk", "slaney" or "kaldi".

AI-assisted analysis of huggingface/transformers@a597f97485 (2026-08-14). Data as JSON: /api/errors/de38048bf78594f1. Report an issue: GitHub.