huggingface/transformers · error · ValueError

Require num_frequency_bins: {num_frequency_bins} >= 2

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.

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)

Solutions

1. Pass num_frequency_bins >= 2; for a one-sided STFT it is fft_length // 2 + 1, so use a larger fft_length
2. If the value is computed from a config, validate/print it before the call to find where it collapses
3. 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)

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)

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

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

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

• mel_scale should be one of "htk", "slaney" or "kaldi".
• norm must be one of None or "slaney"
• Require min_frequency: {min_frequency} <= max_frequency: {ma
• You have provided `mel_filters` but `power` is `None`. Mel s
• Cannot use log_mel option '{log_mel}' with power {power}

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