{"record":{"id":"52a1d82c8c730d9c","repo":"huggingface/transformers","slug":"reference-must-be-greater-than-zero","errorCode":null,"errorMessage":"reference must be greater than zero","messagePattern":"reference must be greater than zero","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/transformers/audio_utils.py","lineNumber":1265,"sourceCode":"\n    Args:\n        spectrogram (`np.ndarray`):\n            The input power (mel) spectrogram. Note that a power spectrogram has the amplitudes squared!\n        reference (`float`, *optional*, defaults to 1.0):\n            Sets the input spectrogram value that corresponds to 0 dB. For example, use `np.max(spectrogram)` to set\n            the loudest part to 0 dB. Must be greater than zero.\n        min_value (`float`, *optional*, defaults to `1e-10`):\n            The spectrogram will be clipped to this minimum value before conversion to decibels, to avoid taking\n            `log(0)`. The default of `1e-10` corresponds to a minimum of -100 dB. Must be greater than zero.\n        db_range (`float`, *optional*):\n            Sets the maximum dynamic range in decibels. For example, if `db_range = 80`, the difference between the\n            peak value and the smallest value will never be more than 80 dB. Must be greater than zero.\n\n    Returns:\n        `np.ndarray`: the spectrogram in decibels\n    \"\"\"\n    if reference <= 0.0:\n        raise ValueError(\"reference must be greater than zero\")\n    if min_value <= 0.0:\n        raise ValueError(\"min_value must be greater than zero\")\n\n    reference = max(min_value, reference)\n\n    spectrogram = np.clip(spectrogram, a_min=min_value, a_max=None)\n    spectrogram = 10.0 * (np.log10(spectrogram) - np.log10(reference))\n\n    if db_range is not None:\n        if db_range <= 0.0:\n            raise ValueError(\"db_range must be greater than zero\")\n        spectrogram = np.clip(spectrogram, a_min=spectrogram.max() - db_range, a_max=None)\n\n    return spectrogram\n\n\ndef power_to_db_batch(\n    spectrogram: np.ndarray,","sourceCodeStart":1247,"sourceCodeEnd":1283,"githubUrl":"https://github.com/huggingface/transformers/blob/a597f974857b3d92939971296bc0deb93d33d780/src/transformers/audio_utils.py#L1247-L1283","documentation":"Raised at the top of transformers.audio_utils.power_to_db when reference <= 0.0. The function computes 10*(log10(spectrogram) - log10(reference)), and log10 of a non-positive number is undefined, so a non-positive reference is rejected before any math runs. Note that after the check, reference is raised to max(min_value, reference), so values between 0 and min_value are silently clamped.","triggerScenarios":"Calling power_to_db(spectrogram, reference=0.0) or reference=-3.0; frequently reference is computed dynamically from data, e.g. reference=spectrogram.min() or a masked-out placeholder like -1/-100 that is <= 0.","commonSituations":"Using a sentinel value (0 or -1) as the default for an optional reference parameter; computing reference from a percentile of a spectrogram that is all zeros; passing reference=np.nan also fails since nan <= 0.0 is False but downstream produces NaN — the explicit trigger is a real value <= 0.","solutions":["Pass a positive reference such as reference=1.0 (default) or reference=float(spectrogram.max())","If reference is computed from data, clamp it: reference = max(reference, 1e-10)","Replace sentinel defaults (0, -1) with None and substitute a positive fallback before the call"],"exampleFix":"// before\ndb = power_to_db(spec, reference=spec.min())  # 0.0 if spec has a zero bin\n// after\nref = max(float(spec.min()), 1e-10)\ndb = power_to_db(spec, reference=ref)","handlingStrategy":"validation","validationCode":"reference = max(float(reference), 1e-10)\ndb = power_to_db(spec, reference=reference)","typeGuard":"def is_positive_reference(reference) -> bool:\n    return isinstance(reference, (int, float)) and reference > 0.0","tryCatchPattern":"try:\n    db = power_to_db(spec, reference=reference)\nexcept ValueError as e:\n    if \"reference must be greater than zero\" in str(e):\n        db = power_to_db(spec, reference=1.0)\n    else:\n        raise","preventionTips":["Never use 0 or -1 as a sentinel for reference; use None and substitute 1.0","Clamp data-derived references with max(value, 1e-10)","Prefer reference=float(spec.max()) to normalize to 0 dB at the peak"],"tags":["audio","validation","decibels","numerical"],"backgroundTag":null,"analyzedSha":"a597f974857b3d92939971296bc0deb93d33d780","analyzedAt":"2026-08-14T18:24:08.354Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}