home-assistant/core · error · ValueError

noise_suppression_level must be in [0, 4]

Error message

noise_suppression_level must be in [0, 4]

What it means

ValueError raised in AudioSettings.__post_init__ (assist_pipeline) when noise_suppression_level is outside [0, 4]. It is a constructor-time invariant check on the dataclass that configures the audio enhancer for a pipeline run.

Source

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

    noise_suppression_level: int = 0
    """Level of noise suppression (0 = disabled, 4 = max)"""

    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."""

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Clamp the value to 0..4 before constructing AudioSettings (0 = disabled, 4 = max suppression).
2. Validate at your config boundary (schema with vol.All(vol.Coerce(int), vol.Range(0, 4))).
3. If you intended stronger suppression, note the library caps at 4; use a dedicated processor instead.

Example fix

# before
settings = AudioSettings(noise_suppression_level=7)
# after
settings = AudioSettings(noise_suppression_level=min(max(level, 0), 4))

import voluptuous as vol

noise_schema = vol.All(vol.Coerce(int), vol.Range(min=0, max=4))
safe_level = noise_schema(raw_value)

Construct AudioSettings inside try/except ValueError and reject the offending config value at the boundary with a clear message instead of letting construction fail deep in a pipeline run.

When it happens

Trigger: Instantiating AudioSettings(noise_suppression_level=-1) or (>4), or building it from unvalidated config/websocket options (e.g. a UI or script sending 5) before running a pipeline.

Common situations: Custom pipeline options set via YAML/websocket with out-of-range values; copy-pasted config from docs with a different scale; negative values from arithmetic on user input.

Related errors

• auto_gain_dbfs must be in [0, 31]
• 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/c9d0a267f7169b80. Report an issue: GitHub.