huggingface/transformers · error · ValueError

reference must be greater than zero

Error message

reference must be greater than zero

What it means

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.

Source

Thrown at src/transformers/audio_utils.py:1265

    Args:
        spectrogram (`np.ndarray`):
            The input power (mel) spectrogram. Note that a power spectrogram has the amplitudes squared!
        reference (`float`, *optional*, defaults to 1.0):
            Sets the input spectrogram value that corresponds to 0 dB. For example, use `np.max(spectrogram)` to set
            the loudest part to 0 dB. Must be greater than zero.
        min_value (`float`, *optional*, defaults to `1e-10`):
            The spectrogram will be clipped to this minimum value before conversion to decibels, to avoid taking
            `log(0)`. The default of `1e-10` corresponds to a minimum of -100 dB. Must be greater than zero.
        db_range (`float`, *optional*):
            Sets the maximum dynamic range in decibels. For example, if `db_range = 80`, the difference between the
            peak value and the smallest value will never be more than 80 dB. Must be greater than zero.

    Returns:
        `np.ndarray`: the spectrogram in decibels
    """
    if reference <= 0.0:
        raise ValueError("reference must be greater than zero")
    if min_value <= 0.0:
        raise ValueError("min_value must be greater than zero")

    reference = max(min_value, reference)

    spectrogram = np.clip(spectrogram, a_min=min_value, a_max=None)
    spectrogram = 10.0 * (np.log10(spectrogram) - np.log10(reference))

    if db_range is not None:
        if db_range <= 0.0:
            raise ValueError("db_range must be greater than zero")
        spectrogram = np.clip(spectrogram, a_min=spectrogram.max() - db_range, a_max=None)

    return spectrogram


def power_to_db_batch(
    spectrogram: np.ndarray,

View on GitHub (pinned to a597f97485)

Solutions

1. Pass a positive reference such as reference=1.0 (default) or reference=float(spectrogram.max())
2. If reference is computed from data, clamp it: reference = max(reference, 1e-10)
3. Replace sentinel defaults (0, -1) with None and substitute a positive fallback before the call

Example fix

// before
db = power_to_db(spec, reference=spec.min())  # 0.0 if spec has a zero bin
// after
ref = max(float(spec.min()), 1e-10)
db = power_to_db(spec, reference=ref)

reference = max(float(reference), 1e-10)
db = power_to_db(spec, reference=reference)

def is_positive_reference(reference) -> bool:
    return isinstance(reference, (int, float)) and reference > 0.0

try:
    db = power_to_db(spec, reference=reference)
except ValueError as e:
    if "reference must be greater than zero" in str(e):
        db = power_to_db(spec, reference=1.0)
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• min_value must be greater than zero
• db_range must be greater than zero
• Unexpected fields in the request: {unexpected}
• PUSH_TO_HUB_TOKEN is not set, cannot push results to the Hub
• Invalid input type. Must be a single audio or a list of audi

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