huggingface/transformers · error · ValueError

db_range must be greater than zero

Error message

db_range must be greater than zero

What it means

Raised inside power_to_db only when db_range is not None and db_range <= 0.0. db_range caps the dynamic range by clipping to spectrogram.max() - db_range; a zero or negative range is meaningless (a range of 0 would flatten everything to the max) so it is rejected after the dB conversion but before clipping.

Source

Thrown at src/transformers/audio_utils.py:1276

            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,
    reference: float = 1.0,
    min_value: float = 1e-10,
    db_range: float | None = None,
) -> np.ndarray:
    """
    Converts a batch of power spectrograms to the decibel scale. This computes `10 * log10(spectrogram / reference)`,
    using basic logarithm properties for numerical stability.

    This function supports batch processing, where each item in the batch is an individual power (mel) spectrogram.

    Args:

View on GitHub (pinned to a597f97485)

Solutions

1. Pass a positive db_range such as 80, or None to disable range clipping entirely
2. If db_range comes from a config, treat 0/missing as None: db_range = cfg.db_range or None
3. When deriving db_range from data, guard: db_range = db_range if db_range and db_range > 0 else None

Example fix

// before
db = power_to_db(spec, db_range=0)      # placeholder leaking through
// after
db = power_to_db(spec, db_range=None)   # or a positive value like 80

db_range = db_range if (db_range is not None and db_range > 0) else None
db = power_to_db(spec, db_range=db_range)

def is_valid_db_range(db_range) -> bool:
    return db_range is None or (isinstance(db_range, (int, float)) and db_range > 0.0)

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

When it happens

Trigger: Calling power_to_db(spec, db_range=0) or db_range=-80; commonly db_range is set from a config default that was initialized to 0, or from a subtraction that yields 0 (e.g. db_range=peak-floor where peak==floor).

Common situations: Configs with db_range=0 as a 'not set' placeholder that is actually passed as a value instead of None; porting torchaudio/librosa code where range parameters are sometimes expressed inverted (e.g. top_db=80 mapped to db_range=-80 by mistake).

Related errors

• reference must be greater than zero
• min_value must be greater than zero
• Stage_names must be set for transformers backbones
• out_features must be a list got {type(self._out_features)}
• out_features must be a subset of stage_names: {self.stage_na

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