{"record":{"id":"3f8209ac267bf84f","repo":"huggingface/transformers","slug":"require-num-frequency-bins-num-frequency-bins","errorCode":null,"errorMessage":"Require num_frequency_bins: {num_frequency_bins} >= 2","messagePattern":"Require num_frequency_bins: (.+?) >= 2","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/audio_utils.py","lineNumber":695,"sourceCode":"        sampling_rate (`int`):\n            Sample rate of the audio waveform.\n        norm (`str`, *optional*):\n            If `\"slaney\"`, divide the triangular mel weights by the width of the mel band (area normalization).\n        mel_scale (`str`, *optional*, defaults to `\"htk\"`):\n            The mel frequency scale to use, `\"htk\"`, `\"kaldi\"` or `\"slaney\"`.\n        triangularize_in_mel_space (`bool`, *optional*, defaults to `False`):\n            If this option is enabled, the triangular filter is applied in mel space rather than frequency space. This\n            should be set to `true` in order to get the same results as `torchaudio` when computing mel filters.\n\n    Returns:\n        `np.ndarray` of shape (`num_frequency_bins`, `num_mel_filters`): Triangular filter bank matrix. This is a\n        projection matrix to go from a spectrogram to a mel spectrogram.\n    \"\"\"\n    if norm is not None and norm != \"slaney\":\n        raise ValueError('norm must be one of None or \"slaney\"')\n\n    if num_frequency_bins < 2:\n        raise ValueError(f\"Require num_frequency_bins: {num_frequency_bins} >= 2\")\n\n    if min_frequency > max_frequency:\n        raise ValueError(f\"Require min_frequency: {min_frequency} <= max_frequency: {max_frequency}\")\n\n    # center points of the triangular mel filters\n    mel_min = hertz_to_mel(min_frequency, mel_scale=mel_scale)\n    mel_max = hertz_to_mel(max_frequency, mel_scale=mel_scale)\n    mel_freqs = np.linspace(mel_min, mel_max, num_mel_filters + 2)\n    filter_freqs = mel_to_hertz(mel_freqs, mel_scale=mel_scale)\n\n    if triangularize_in_mel_space:\n        # frequencies of FFT bins in Hz, but filters triangularized in mel space\n        fft_bin_width = sampling_rate / ((num_frequency_bins - 1) * 2)\n        fft_freqs = hertz_to_mel(fft_bin_width * np.arange(num_frequency_bins), mel_scale=mel_scale)\n        filter_freqs = mel_freqs\n    else:\n        # frequencies of FFT bins in Hz\n        fft_freqs = np.linspace(0, sampling_rate // 2, num_frequency_bins)","sourceCodeStart":677,"sourceCodeEnd":713,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/audio_utils.py#L677-L713","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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"],"exampleFix":"// before\nmel_filters = mel_filter_bank(num_frequency_bins=1, num_mel_filters=80, sampling_rate=16000)  # ValueError\n\n// after\nmel_filters = mel_filter_bank(num_frequency_bins=257, num_mel_filters=80, sampling_rate=16000)","handlingStrategy":"validation","validationCode":"if num_frequency_bins < 2:\n    raise ValueError(f\"num_frequency_bins must be >= 2, got {num_frequency_bins}\")\nmel = mel_filter_bank(num_frequency_bins=num_frequency_bins, num_mel_filters=80, sampling_rate=16000)","typeGuard":"def has_valid_bin_count(n: int) -> bool:\n    return isinstance(n, (int, np.integer)) and n >= 2","tryCatchPattern":"try:\n    mel = mel_filter_bank(num_frequency_bins=bins, ...)\nexcept ValueError as e:\n    if \"num_frequency_bins\" in str(e):\n        raise ValueError(f\"Computed bins={bins}; use a larger fft_length (one-sided bins = fft_length//2+1)\") from e\n    raise","preventionTips":["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"],"tags":["audio","mel-spectrogram","argument-validation"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}