home-assistant/core · error · SpeechToTextError

cloud-auth-failed

cloud-auth-failed

Error message

Home Assistant Cloud authentication failed

What it means

SpeechToTextError with code cloud-auth-failed is raised when Home Assistant Cloud (Nabu Casa) speech-to-text raises hass_nabucasa.auth.Unauthenticated during async_process_audio_stream. The pipeline converts it to a pipeline error because the cloud credentials are no longer valid, so the remote STT service refuses the request.

Source

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

        try:
            # Transcribe audio stream
            stt_vad: VoiceCommandSegmenter | None = None
            if (
                self.audio_settings.is_vad_enabled
                and self.stt_provider.audio_processing.requires_external_vad
            ):
                stt_vad = VoiceCommandSegmenter(
                    silence_seconds=self.audio_settings.silence_seconds
                )

            result = await self.stt_provider.async_process_audio_stream(
                metadata,
                self._speech_to_text_stream(audio_stream=stream, stt_vad=stt_vad),
            )
        except asyncio.CancelledError, TimeoutError:
            raise  # expected
        except hass_nabucasa.auth.Unauthenticated as src_error:
            raise SpeechToTextError(
                code="cloud-auth-failed",
                message="Home Assistant Cloud authentication failed",
            ) from src_error
        except Exception as src_error:
            _LOGGER.exception("Unexpected error during speech-to-text")
            raise SpeechToTextError(
                code="stt-stream-failed",
                message="Unexpected error during speech-to-text",
            ) from src_error

        _LOGGER.debug("speech-to-text result %s", result)

        if result.result != stt.SpeechResultState.SUCCESS:
            raise SpeechToTextError(
                code="stt-stream-failed",
                message="speech-to-text failed",
            )

View on GitHub (pinned to 58a3fdb3ea)

Solutions

  1. Re-authenticate Home Assistant Cloud: Settings > Home Assistant Cloud, log out and back in, then retry.
  2. Verify the Nabu Casa subscription is active and not expired.
  3. If cloud is intentionally unavailable, switch the pipeline's stt_engine to a local provider (e.g. Whisper via Wyoming).

Example fix

# before
pipeline = Pipeline(stt_engine="cloud_stt")  # cloud token expired

# after: use a local engine when cloud auth is not available
cloud = hass.data["hass_nabucasa"].cloud
if not cloud.is_logged_in:
    pipeline = dataclasses.replace(pipeline, stt_engine="whisper.local")
Defensive patterns

Strategy: fallback

Validate before calling

cloud = hass.data.get("hass_nabucasa", {}).get("cloud")
if pipeline.stt_engine == "cloud_stt" and (cloud is None or not cloud.is_logged_in):
    pipeline = dataclasses.replace(pipeline, stt_engine="<local engine id>")

Try / catch

from homeassistant.components.assist_pipeline.error import SpeechToTextError
try:
    await pipeline_job.run()
except SpeechToTextError as err:
    if err.code == "cloud-auth-failed":
        persistent_notification.create(hass, "Re-authenticate Home Assistant Cloud", "assist")

Prevention

When it happens

Trigger: A pipeline whose stt_engine is the cloud STT provider runs while the stored cloud authentication token is expired or revoked; the nabucasa client raises Unauthenticated and the STT stage rethrows this error chained from it.

Common situations: Nabu Casa subscription lapsed or was canceled, the user logged out of cloud or re-authenticated on another instance, tokens invalidated server-side, or a long-lived instance with stale cloud credentials.

Understand the failure class

Related errors

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