{"record":{"id":"2e446f240a180dc7","repo":"home-assistant/core","slug":"auto-gain-dbfs-must-be-in-0-31","errorCode":null,"errorMessage":"auto_gain_dbfs must be in [0, 31]","messagePattern":"auto_gain_dbfs must be in \\[0, 31\\]","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"homeassistant/components/assist_pipeline/pipeline.py","lineNumber":531,"sourceCode":"    auto_gain_dbfs: int = 0\n    \"\"\"Amount of automatic gain in dbFS (0 = disabled, 31 = max)\"\"\"\n\n    volume_multiplier: float = 1.0\n    \"\"\"Multiplier used directly on PCM samples (1.0 = no change, 2.0 = twice as loud)\"\"\"\n\n    is_vad_enabled: bool = True\n    \"\"\"True if VAD is used to determine the end of the voice command.\"\"\"\n\n    silence_seconds: float = 0.7\n    \"\"\"Seconds of silence after voice command has ended.\"\"\"\n\n    def __post_init__(self) -> None:\n        \"\"\"Verify settings post-initialization.\"\"\"\n        if (self.noise_suppression_level < 0) or (self.noise_suppression_level > 4):\n            raise ValueError(\"noise_suppression_level must be in [0, 4]\")\n\n        if (self.auto_gain_dbfs < 0) or (self.auto_gain_dbfs > 31):\n            raise ValueError(\"auto_gain_dbfs must be in [0, 31]\")\n\n    @property\n    def needs_processor(self) -> bool:\n        \"\"\"True if an audio processor is needed.\"\"\"\n        return (\n            self.is_vad_enabled\n            or (self.noise_suppression_level > 0)\n            or (self.auto_gain_dbfs > 0)\n        )\n\n\n@dataclass\nclass PipelineRun:\n    \"\"\"Running context for a pipeline.\"\"\"\n\n    hass: HomeAssistant\n    context: Context\n    pipeline: Pipeline","sourceCodeStart":513,"sourceCodeEnd":549,"githubUrl":"https://github.com/home-assistant/core/blob/58a3fdb3ea0538617f0a07efcfba6294de64fd59/homeassistant/components/assist_pipeline/pipeline.py#L513-L549","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Restrict auto_gain_dbfs to 0..31 dBFS (0 = off).","Add a vol.Range(0, 31) (or equivalent) validator where the value enters your code.","Re-check the value after restoring backups of pipeline configs from other instances."],"exampleFix":"# before\nsettings = AudioSettings(auto_gain_dbfs=50)\n# after\nsettings = AudioSettings(auto_gain_dbfs=min(max(gain_dbfs, 0), 31))","handlingStrategy":"validation","validationCode":"import voluptuous as vol\n\ngain_schema = vol.All(vol.Coerce(int), vol.Range(min=0, max=31))\nsafe_gain = gain_schema(raw_gain)","typeGuard":null,"tryCatchPattern":"Catch ValueError from AudioSettings(...) construction in option-loading code and report the invalid field back to the user instead of crashing the pipeline setup.","preventionTips":["Validate auto_gain_dbfs to 0..31 dBFS where the value originates.","Clamp computed gain values before use.","Unit-check inputs: the field is dBFS, not percent or percent/100."],"tags":["home-assistant","assist-pipeline","validation","audio","constructor"],"backgroundTag":null,"analyzedSha":"58a3fdb3ea0538617f0a07efcfba6294de64fd59","analyzedAt":"2026-08-14T20:54:38.818Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}