What causes "Unexpected error during wake-word-detection" in home-assistant/core?

Read the logged 'Unexpected error during wake-word-detection' traceback - it names the real failure (file missing, OOM, etc.).

home-assistant/core · error · WakeWordDetectionError

wake-stream-failed

wake-stream-failed

Error message

Unexpected error during wake-word-detection

What it means

WakeWordDetectionError with code 'wake-stream-failed' raised by PipelineRun.wake_word_detection as a catch-all after the wake-word entity's async_process_audio_stream raised an unexpected exception (not WakeWordDetectionAborted or WakeWordTimeoutError). The original exception is logged with a traceback and chained as __cause__.

Source

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

                    audio_stream=stream,
                    stt_audio_buffer=stt_audio_buffer,
                    wake_word_vad=wake_word_vad,
                ),
                self.pipeline.wake_word_id,
            )

            if stt_audio_buffer is not None:
                # All audio kept from right before the wake word was detected as
                # a single chunk.
                audio_chunks_for_stt.extend(stt_audio_buffer)
        except WakeWordDetectionAborted:
            raise
        except WakeWordTimeoutError:
            _LOGGER.debug("Timeout during wake word detection")
            raise
        except Exception as src_error:
            _LOGGER.exception("Unexpected error during wake-word-detection")
            raise WakeWordDetectionError(
                code="wake-stream-failed",
                message="Unexpected error during wake-word-detection",
            ) from src_error

        _LOGGER.debug("wake-word-detection result %s", result)

        if result is None:
            wake_word_output: dict[str, Any] = {}
        else:
            # Avoid duplicate detections by checking cooldown
            last_wake_up = self.hass.data[DATA_LAST_WAKE_UP].get(
                result.wake_word_phrase
            )
            if last_wake_up is not None:
                sec_since_last_wake_up = time.monotonic() - last_wake_up
                if sec_since_last_wake_up < WAKE_WORD_COOLDOWN:
                    _LOGGER.debug(
                        "Duplicate wake word detection occurred for %s",

View on GitHub (pinned to 58a3fdb3ea)

Solutions

Read the logged 'Unexpected error during wake-word-detection' traceback - it names the real failure (file missing, OOM, etc.).
Re-download/reinstall the wake word models (e.g. clear the openWakeWord models cache).
Reduce concurrent wake-word streams or move inference off a memory-constrained host.
Update the wake word provider integration/library to a compatible version.

Defensive patterns

Strategy: try-catch

Try / catch

Catch WakeWordDetectionAborted and WakeWordTimeoutError separately and re-raise; wrap everything else in a broad except Exception that logs the traceback (LOGGER.exception) and raises WakeWordDetectionError(code='wake-stream-failed') from src_error - the integration's own pattern.

Prevention

Verify wake word model files are present and loadable before streaming.
Log and inspect the chained cause; the code 'wake-stream-failed' is only a wrapper.
Monitor memory on the inference host to avoid OOM kills mid-stream.

When it happens

Trigger: Streaming audio chunks to the wake word entity and its backend crashes: onnx model file missing/corrupt in openWakeWord, out-of-memory in the inference process, or a bug in a custom wake word provider.

Common situations: Incomplete model download for custom wake words; resource exhaustion on low-power hosts (Raspberry Pi) running multiple pipelines; provider integration updated with an incompatible model format.

Related errors

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