{"record":{"id":"5639f51d14ad024a","repo":"huggingface/transformers","slug":"hop-length-must-be-greater-than-zero","errorCode":null,"errorMessage":"hop_length must be greater than zero","messagePattern":"hop_length must be greater than zero","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/audio_utils.py","lineNumber":939,"sourceCode":"            `np.complex64`.\n\n    Returns:\n        `nd.array` containing a spectrogram of shape `(num_frequency_bins, length)` for a regular spectrogram or shape\n        `(num_mel_filters, length)` for a mel spectrogram.\n    \"\"\"\n    window_length = len(window)\n\n    if fft_length is None:\n        fft_length = frame_length\n\n    if frame_length > fft_length:\n        raise ValueError(f\"frame_length ({frame_length}) may not be larger than fft_length ({fft_length})\")\n\n    if window_length != frame_length:\n        raise ValueError(f\"Length of the window ({window_length}) must equal frame_length ({frame_length})\")\n\n    if hop_length <= 0:\n        raise ValueError(\"hop_length must be greater than zero\")\n\n    if waveform.ndim != 1:\n        raise ValueError(f\"Input waveform must have only one dimension, shape is {waveform.shape}\")\n\n    if np.iscomplexobj(waveform):\n        raise ValueError(\"Complex-valued input waveforms are not currently supported\")\n\n    if power is None and mel_filters is not None:\n        raise ValueError(\n            \"You have provided `mel_filters` but `power` is `None`. Mel spectrogram computation is not yet supported for complex-valued spectrogram.\"\n            \"Specify `power` to fix this issue.\"\n        )\n\n    # center pad the waveform\n    if center:\n        padding = [(int(frame_length // 2), int(frame_length // 2))]\n        waveform = np.pad(waveform, padding, mode=pad_mode)\n","sourceCodeStart":921,"sourceCodeEnd":957,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/audio_utils.py#L921-L957","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Pass a positive hop_length (typical values are frame_length//4 or a fixed 160 for 16 kHz audio)","If hop_length is computed, assert it is >= 1 before calling (e.g. max(1, int(...)))","Fix the processor config key that supplies hop_length"],"exampleFix":"// before\nspec = spectrogram(waveform, window, frame_length=400, hop_length=0)  # ValueError\n\n// after\nspec = spectrogram(waveform, window, frame_length=400, hop_length=160)","handlingStrategy":"validation","validationCode":"if hop_length is None or hop_length <= 0:\n    raise ValueError(f\"hop_length must be a positive int, got {hop_length!r}\")\nspec = spectrogram(waveform, window, frame_length, hop_length)","typeGuard":"def is_valid_hop(h: int) -> bool:\n    return isinstance(h, (int, np.integer)) and h >= 1","tryCatchPattern":"try:\n    spec = spectrogram(waveform, window, frame_length, hop_length)\nexcept ValueError as e:\n    if \"hop_length\" in str(e):\n        hop_length = max(1, frame_length // 4)\n        spec = spectrogram(waveform, window, frame_length, hop_length)\n    else:\n        raise","preventionTips":["Use conventional hops (160 at 16 kHz, or frame_length//4)","Clamp computed hops: max(1, int(...))","Validate processor config values before batch runs"],"tags":["audio","stft","argument-validation"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}