huggingface/transformers · error · ValueError

You have provided `mel_filters` but `power` is `None`. Mel s

Error message

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.

What it means

Thrown by `spectrogram` when `mel_filters` is provided but `power` is None. Mel spectrograms are computed by projecting a power spectrogram onto the mel filter bank; with power=None the function returns a complex-valued STFT, and mel projection of complex values is not implemented, so the combination is rejected. The message is split across two string literals so it reads as one sentence ending '...fix this issue.'.

Source

Thrown at src/transformers/audio_utils.py:948

        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."
        )

    # center pad the waveform
    if center:
        padding = [(int(frame_length // 2), int(frame_length // 2))]
        waveform = np.pad(waveform, padding, mode=pad_mode)

    # promote to float64, since np.fft uses float64 internally
    waveform = waveform.astype(np.float64)
    window = window.astype(np.float64)

    # split waveform into frames of frame_length size
    num_frames = int(1 + np.floor((waveform.size - frame_length) / hop_length))

    num_frequency_bins = (fft_length // 2) + 1 if onesided else fft_length
    spectrogram = np.empty((num_frames, num_frequency_bins), dtype=np.complex64)

View on GitHub (pinned to a597f97485)

Solutions

Set power to a float (1.0 for magnitude, 2.0 for power spectrogram) when using mel_filters
If you truly need a complex STFT, drop the mel_filters argument
Validate that configs do not combine power=null with mel filter settings

Example fix

// before
mel = mel_filter_bank(257, 80, 16000)
spec = spectrogram(waveform, window, 400, 160, power=None, mel_filters=mel)  # ValueError

// after
spec = spectrogram(waveform, window, 400, 160, power=2.0, mel_filters=mel)

Defensive patterns

Strategy: validation

Validate before calling

if mel_filters is not None:
    power = power if power is not None else 2.0  # mel requires a real-valued (power) spectrogram
spec = spectrogram(waveform, window, frame_length, hop_length, power=power, mel_filters=mel_filters)

Type guard

def mel_config_is_consistent(power, mel_filters) -> bool:
    return mel_filters is None or power is not None

Try / catch

try:
    spec = spectrogram(waveform, window, frame_length, hop_length, power=power, mel_filters=mel_filters)
except ValueError as e:
    if "mel_filters" in str(e) and "power" in str(e):
        spec = spectrogram(waveform, window, frame_length, hop_length, power=2.0, mel_filters=mel_filters)
    else:
        raise

Prevention

Always pair mel_filters with an explicit power (2.0 is standard)
For complex STFT output, omit mel_filters entirely
Reject configs that combine power=null with mel settings

When it happens

Trigger: Calling `spectrogram(waveform, window, frame_length, hop_length, power=None, mel_filters=some_mel_filter_bank(...))`. Common when implementing a complex STFT pipeline and reusing the mel path, or when power was accidentally set to None from a config default.

Common situations: Custom feature extractors that pass mel_filters unconditionally but make power configurable; porting code that expects complex spectrograms; configs where 'power': null appears alongside mel settings.

Related errors

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