home-assistant/core · error · ValueError

auto_gain_dbfs must be in [0, 31]

Error message

auto_gain_dbfs must be in [0, 31]

What it means

ValueError raised in AudioSettings.__post_init__ (assist_pipeline) when auto_gain_dbfs is outside [0, 31]. Like its sibling check for noise suppression, it enforces the valid dBFS range for the auto-gain stage of the audio enhancer at dataclass construction time.

Source

Thrown at homeassistant/components/assist_pipeline/pipeline.py:531

    auto_gain_dbfs: int = 0
    """Amount of automatic gain in dbFS (0 = disabled, 31 = max)"""

    volume_multiplier: float = 1.0
    """Multiplier used directly on PCM samples (1.0 = no change, 2.0 = twice as loud)"""

    is_vad_enabled: bool = True
    """True if VAD is used to determine the end of the voice command."""

    silence_seconds: float = 0.7
    """Seconds of silence after voice command has ended."""

    def __post_init__(self) -> None:
        """Verify settings post-initialization."""
        if (self.noise_suppression_level < 0) or (self.noise_suppression_level > 4):
            raise ValueError("noise_suppression_level must be in [0, 4]")

        if (self.auto_gain_dbfs < 0) or (self.auto_gain_dbfs > 31):
            raise ValueError("auto_gain_dbfs must be in [0, 31]")

    @property
    def needs_processor(self) -> bool:
        """True if an audio processor is needed."""
        return (
            self.is_vad_enabled
            or (self.noise_suppression_level > 0)
            or (self.auto_gain_dbfs > 0)
        )


@dataclass
class PipelineRun:
    """Running context for a pipeline."""

    hass: HomeAssistant
    context: Context
    pipeline: Pipeline

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Restrict auto_gain_dbfs to 0..31 dBFS (0 = off).
2. Add a vol.Range(0, 31) (or equivalent) validator where the value enters your code.
3. Re-check the value after restoring backups of pipeline configs from other instances.

Example fix

# before
settings = AudioSettings(auto_gain_dbfs=50)
# after
settings = AudioSettings(auto_gain_dbfs=min(max(gain_dbfs, 0), 31))

import voluptuous as vol

gain_schema = vol.All(vol.Coerce(int), vol.Range(min=0, max=31))
safe_gain = gain_schema(raw_gain)

Catch ValueError from AudioSettings(...) construction in option-loading code and report the invalid field back to the user instead of crashing the pipeline setup.

When it happens

Trigger: AudioSettings(auto_gain_dbfs=-3) or auto_gain_dbfs=40 passed to a PipelineRun; typically from user-supplied pipeline options that were not range-validated upstream.

Common situations: Manually edited YAML/JSON pipeline options; automations computing gain from microphone sensitivity values in a different unit; UI sliders with a wider range than the library accepts.

Related errors

• noise_suppression_level must be in [0, 4]
• pipeline_not_found
• validation-error
• username_not_normalized
• Operation mode not supported

AI-assisted analysis of home-assistant/core@58a3fdb3ea (2026-08-14). Data as JSON: /api/errors/2e446f240a180dc7. Report an issue: GitHub.