home-assistant/core · error · TextToSpeechError

tts-not-supported

tts-not-supported

Error message

Text-to-speech engine {engine} does not support language {self.pipeline.tts_language} or options {tts_options}: {err}

What it means

TextToSpeechError with code tts-not-supported is raised in prepare_text_to_speech when tts.async_create_stream raises a HomeAssistantError while resolving the engine against the requested language and options (including preferred sample rate/channels/bytes that the pipeline injects for voice satellites). It means the selected TTS engine cannot synthesize this language/option combination.

Source

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

        if isinstance(self.tts_audio_output, dict):
            tts_options.update(self.tts_audio_output)
        elif isinstance(self.tts_audio_output, str):
            tts_options[tts.ATTR_PREFERRED_FORMAT] = self.tts_audio_output
            if self.tts_audio_output == "wav":
                # 16 Khz, 16-bit mono
                tts_options[tts.ATTR_PREFERRED_SAMPLE_RATE] = SAMPLE_RATE
                tts_options[tts.ATTR_PREFERRED_SAMPLE_CHANNELS] = SAMPLE_CHANNELS
                tts_options[tts.ATTR_PREFERRED_SAMPLE_BYTES] = SAMPLE_WIDTH

        try:
            self.tts_stream = tts.async_create_stream(
                hass=self.hass,
                engine=engine,
                language=self.pipeline.tts_language,
                options=tts_options,
            )
        except HomeAssistantError as err:
            raise TextToSpeechError(
                code="tts-not-supported",
                message=(
                    f"Text-to-speech engine {engine} "
                    f"does not support language {self.pipeline.tts_language}"
                    f" or options {tts_options}:"
                    f" {err}"
                ),
            ) from err

    async def text_to_speech(
        self, tts_input: str, override_media_path: Path | None = None
    ) -> None:
        """Run text-to-speech portion of pipeline."""
        assert self.tts_stream is not None

        self.process_event(
            PipelineEvent(
                PipelineEventType.TTS_START,

View on GitHub (pinned to 58a3fdb3ea)

Solutions

Check the engine's supported languages (e.g. via tts engine info or its documentation) and set pipeline.tts_language to one of them.
Remove or adjust unsupported tts options (sample rate/channels/bytes) in the pipeline or request.
Switch to a TTS engine that covers the needed language (cloud TTS for broad coverage, Piper with an appropriate voice).
If the engine id itself is stale, re-select a valid tts_engine in the pipeline settings.

Example fix

# before
run = pipeline.start(tts_input="Hello", tts_engine="tts.piper", tts_language="ja-JP")
# piper voice only supports en-US -> tts-not-supported

# after
supported = tts.async_get_supported_languages(hass, "tts.piper")
language = "ja-JP" if "ja-JP" in supported else "en-US"
run = pipeline.start(tts_input="Hello", tts_engine="tts.piper", tts_language=language)

Defensive patterns

Strategy: validation

Validate before calling

from homeassistant.components import tts
languages = tts.async_get_supported_languages(hass, engine_id)
if (pipeline.tts_language or hass.config.language) not in languages:
    _LOGGER.warning("TTS language unsupported: %s", pipeline.tts_language)

Try / catch

from homeassistant.components.assist_pipeline.error import TextToSpeechError
try:
    await pipeline_job.run()
except TextToSpeechError as err:
    if err.code == "tts-not-supported":
        # choose supported language/engine
        ...

Prevention

Check engine language lists before setting pipeline.tts_language.
Avoid injecting sample rate/channel options the engine cannot produce.
For multilingual setups, prefer cloud TTS or map languages to engines explicitly.

When it happens

Trigger: A run ending at the TTS stage with pipeline.tts_language (or the effective language) or tts_options unsupported by the configured tts_engine, so async_create_stream fails during preparation.

Common situations: Cloud TTS requested for a language the user's voice does not support, Piper voice missing a locale, a preferred sample rate the engine cannot produce, or a tts engine entity that was removed while the pipeline still names it.

Related errors

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