What causes "Require num_frequency_bins: {num_frequency_bins} >= 2" in huggingface/transformers?

Pass num_frequency_bins >= 2; for a one-sided STFT it is fft_length // 2 + 1, so use a larger fft_length

huggingface/transformers · error · ValueError

Require num_frequency_bins

Error message

Require num_frequency_bins: {num_frequency_bins} >= 2

What it means

Thrown by `mel_filter_bank` when `num_frequency_bins < 2`. A mel filter bank is a projection matrix of shape (num_frequency_bins, num_mel_filters); with fewer than 2 frequency bins there is no interval to place triangular filters over, so the matrix cannot be constructed. The check runs after the norm check and before frequency conversion.

Solutions

Pass num_frequency_bins >= 2; for a one-sided STFT it is fft_length // 2 + 1, so use a larger fft_length
If the value is computed from a config, validate/print it before the call to find where it collapses
Check that num_frequency_bins and num_mel_filters arguments were not accidentally swapped

Example fix

// before
mel_filters = mel_filter_bank(num_frequency_bins=1, num_mel_filters=80, sampling_rate=16000)  # ValueError

// after
mel_filters = mel_filter_bank(num_frequency_bins=257, num_mel_filters=80, sampling_rate=16000)

Defensive patterns

Strategy: validation

Validate before calling

if num_frequency_bins < 2:
    raise ValueError(f"num_frequency_bins must be >= 2, got {num_frequency_bins}")
mel = mel_filter_bank(num_frequency_bins=num_frequency_bins, num_mel_filters=80, sampling_rate=16000)

Type guard

def has_valid_bin_count(n: int) -> bool:
    return isinstance(n, (int, np.integer)) and n >= 2

Try / catch

try:
    mel = mel_filter_bank(num_frequency_bins=bins, ...)
except ValueError as e:
    if "num_frequency_bins" in str(e):
        raise ValueError(f"Computed bins={bins}; use a larger fft_length (one-sided bins = fft_length//2+1)") from e
    raise

Prevention

Derive bins as fft_length // 2 + 1 and assert fft_length >= 2
Sanity-check dynamically computed dimensions in unit tests
Do not swap num_frequency_bins and num_mel_filters

When it happens

Trigger: Calling `mel_filter_bank` with num_frequency_bins=0 or 1, or with a computed value such as fft_length//2+1 that evaluates to 1 (e.g. fft_length=2). Feature extractors computing num_frequency_bins from a tiny n_fft hit this.

Common situations: Unit tests or CI jobs with degenerate tiny FFT sizes; dynamically deriving num_frequency_bins from a config that got set to a near-zero value; copy-paste errors swapping num_mel_filters and num_frequency_bins.

Related errors

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

Appendix: source

Thrown at src/transformers/audio_utils.py:695

        sampling_rate (`int`):
            Sample rate of the audio waveform.
        norm (`str`, *optional*):
            If `"slaney"`, divide the triangular mel weights by the width of the mel band (area normalization).
        mel_scale (`str`, *optional*, defaults to `"htk"`):
            The mel frequency scale to use, `"htk"`, `"kaldi"` or `"slaney"`.
        triangularize_in_mel_space (`bool`, *optional*, defaults to `False`):
            If this option is enabled, the triangular filter is applied in mel space rather than frequency space. This
            should be set to `true` in order to get the same results as `torchaudio` when computing mel filters.

    Returns:
        `np.ndarray` of shape (`num_frequency_bins`, `num_mel_filters`): Triangular filter bank matrix. This is a
        projection matrix to go from a spectrogram to a mel spectrogram.
    """
    if norm is not None and norm != "slaney":
        raise ValueError('norm must be one of None or "slaney"')

    if num_frequency_bins < 2:
        raise ValueError(f"Require num_frequency_bins: {num_frequency_bins} >= 2")

    if min_frequency > max_frequency:
        raise ValueError(f"Require min_frequency: {min_frequency} <= max_frequency: {max_frequency}")

    # center points of the triangular mel filters
    mel_min = hertz_to_mel(min_frequency, mel_scale=mel_scale)
    mel_max = hertz_to_mel(max_frequency, mel_scale=mel_scale)
    mel_freqs = np.linspace(mel_min, mel_max, num_mel_filters + 2)
    filter_freqs = mel_to_hertz(mel_freqs, mel_scale=mel_scale)

    if triangularize_in_mel_space:
        # frequencies of FFT bins in Hz, but filters triangularized in mel space
        fft_bin_width = sampling_rate / ((num_frequency_bins - 1) * 2)
        fft_freqs = hertz_to_mel(fft_bin_width * np.arange(num_frequency_bins), mel_scale=mel_scale)
        filter_freqs = mel_freqs
    else:
        # frequencies of FFT bins in Hz
        fft_freqs = np.linspace(0, sampling_rate // 2, num_frequency_bins)

View on GitHub (pinned to a597f97485)