huggingface/transformers · error · ValueError

hop_length must be greater than zero

Error message

hop_length must be greater than zero

What it means

Thrown by `spectrogram` when `hop_length <= 0`. The hop length is the step in samples between consecutive STFT frames; a zero or negative step would produce an infinite or backwards iteration over frames, so it is validated before framing. The check applies to both the single-waveform `spectrogram` and batch variants.

Source

Thrown at src/transformers/audio_utils.py:939

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

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

View on GitHub (pinned to a597f97485)

Solutions

  1. Pass a positive hop_length (typical values are frame_length//4 or a fixed 160 for 16 kHz audio)
  2. If hop_length is computed, assert it is >= 1 before calling (e.g. max(1, int(...)))
  3. Fix the processor config key that supplies hop_length

Example fix

// before
spec = spectrogram(waveform, window, frame_length=400, hop_length=0)  # ValueError

// after
spec = spectrogram(waveform, window, frame_length=400, hop_length=160)
Defensive patterns

Strategy: validation

Validate before calling

if hop_length is None or hop_length <= 0:
    raise ValueError(f"hop_length must be a positive int, got {hop_length!r}")
spec = spectrogram(waveform, window, frame_length, hop_length)

Type guard

def is_valid_hop(h: int) -> bool:
    return isinstance(h, (int, np.integer)) and h >= 1

Try / catch

try:
    spec = spectrogram(waveform, window, frame_length, hop_length)
except ValueError as e:
    if "hop_length" in str(e):
        hop_length = max(1, frame_length // 4)
        spec = spectrogram(waveform, window, frame_length, hop_length)
    else:
        raise

Prevention

When it happens

Trigger: Calling `spectrogram(..., hop_length=0)` or with a negative value, or with hop_length derived from a config arithmetic that evaluated to 0 (e.g. int(frame_length * 0) or a stride key that was misread as 0).

Common situations: Misconfigured feature extractor JSONs with "hop_length": 0; computing hop_length from a fraction that underflows to zero after an int cast; test fixtures parameterized with edge-case strides.

Related errors

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