home-assistant/core · warning · WakeWordTimeoutError

wake-word-timeout

wake-word-timeout

Error message

Wake word was not detected

What it means

WakeWordTimeoutError (code wake-word-timeout) is raised during the WAKE_WORD stage when the voice-activity detector used alongside wake word detection (wake_word_vad) decides the incoming audio is not speech. The VAD runs on every chunk's speech_probability; if process() returns False the pipeline concludes nobody spoke a wake word and aborts the run. This is the expected 'nobody said anything' outcome of a voice pipeline run, not an internal fault.

Source

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

        detection. Times out if VAD detects enough silence.
        """
        async for chunk in audio_stream:
            if self.abort_wake_word_detection:
                raise WakeWordDetectionAborted

            self._capture_chunk(chunk.audio)
            yield chunk.audio, chunk.timestamp_ms

            # Wake-word-detection occurs *after* the wake word was actually
            # spoken. Keeping audio right before detection allows the voice
            # command to be spoken immediately after the wake word.
            if stt_audio_buffer is not None:
                stt_audio_buffer.append(chunk)

            if wake_word_vad is not None:
                chunk_seconds = (len(chunk.audio) // sample_width) / sample_rate
                if not wake_word_vad.process(chunk_seconds, chunk.speech_probability):
                    raise WakeWordTimeoutError(
                        code="wake-word-timeout", message="Wake word was not detected"
                    )

    async def prepare_speech_to_text(self, metadata: stt.SpeechMetadata) -> None:
        """Prepare speech-to-text."""
        # pipeline.stt_engine can't be None or this function is not called
        stt_provider = stt.async_get_speech_to_text_engine(
            self.hass,
            self.pipeline.stt_engine,  # type: ignore[arg-type]
        )

        if stt_provider is None:
            engine = self.pipeline.stt_engine
            raise SpeechToTextError(
                code="stt-provider-missing",
                message=f"No speech-to-text provider for: {engine}",
            )

View on GitHub (pinned to 58a3fdb3ea)

Solutions

  1. Speak the configured wake word directly at the microphone and re-run the pipeline.
  2. Verify the audio reaching the pipeline matches the advertised stt_metadata/wake-word format (16 kHz, 16-bit, mono, AAC/PCM as configured).
  3. If the environment is noisy or detection is too strict, tune or replace the VAD/wake-word engine (e.g. openWakeWord via Wyoming) or adjust its sensitivity settings.
  4. Treat the error as expected idle behavior: listen for PipelineEventType.WAKE_WORD_TIMEOUT in the pipeline events instead of logging it as a failure.

Example fix

# before
await pipeline_job.run()  # raises WakeWordTimeoutError on silence

# after
from homeassistant.components.assist_pipeline.error import WakeWordTimeoutError
try:
    await pipeline_job.run()
except WakeWordTimeoutError:
    _LOGGER.debug("No wake word detected; run ended normally")
Defensive patterns

Strategy: try-catch

Try / catch

from homeassistant.components.assist_pipeline.error import WakeWordTimeoutError
try:
    await pipeline_job.run()
except WakeWordTimeoutError:
    pass  # expected when nobody speaks; not a failure

Prevention

When it happens

Trigger: Calling async_process_wake_word_audio (or PipelineRun starting at PipelineStage.WAKE_WORD) with an audio stream whose chunks have a speech_probability below the VAD threshold, i.e. silence or background noise instead of a spoken wake word.

Common situations: Microphone muted or far from the speaker, satellite device picking up only ambient noise, wrong audio format/rate fed to the pipeline so the VAD misreads it, or a timer-driven run that starts recording before the user speaks.

Related errors

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