home-assistant/core · error · SpeechToTextError

stt-provider-unsupported-metadata

stt-provider-unsupported-metadata

Error message

Provider {stt_provider.name} does not support input speech to text metadata {metadata}

What it means

SpeechToTextError with code stt-provider-unsupported-metadata is raised in prepare_speech_to_text when the resolved provider's check_metadata() rejects the request metadata after the pipeline language was applied. The metadata carries audio format (bitrate, sample rate, channels, sample width) and language; a mismatch means the engine cannot decode this audio stream.

Source

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

    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}",
            )

        metadata.language = self.pipeline.stt_language or self.language

        if not stt_provider.check_metadata(metadata):
            raise SpeechToTextError(
                code="stt-provider-unsupported-metadata",
                message=(
                    f"Provider {stt_provider.name} does not support input speech "
                    f"to text metadata {metadata}"
                ),
            )

        self.stt_provider = stt_provider

    async def speech_to_text(
        self,
        metadata: stt.SpeechMetadata,
        stream: AsyncIterable[EnhancedAudioChunk],
    ) -> str:
        """Run speech-to-text portion of pipeline. Returns the spoken text."""
        # Create a background task to prepare the conversation agent
        if self.end_stage >= PipelineStage.INTENT and self.intent_agent:
            self.hass.async_create_background_task(

View on GitHub (pinned to 58a3fdb3ea)

Solutions

Match the client's audio to the provider's supported formats: typically 16 kHz, 16-bit, 1 channel (PCM), and confirm via the provider's supported_metadata list.
Set pipeline.stt_language to a language the engine supports, or pick an engine that supports the target language.
If a custom provider is involved, fix its check_metadata/supported_metadata implementation.

Example fix

# before
metadata = stt.SpeechMetadata(
    language="", format=stt.AudioFormats.WAV, codec=stt.AudioCodecs.PCM,
    bit_rate=stt.AudioBitRates.BITRATE_8,
    sample_rate=stt.AudioSampleRates.SAMPLERATE_8000,
    channel=stt.AudioChannels.CHANNELS_1,
)

# after
metadata = stt.SpeechMetadata(
    language="", format=stt.AudioFormats.WAV, codec=stt.AudioCodecs.PCM,
    bit_rate=stt.AudioBitRates.BITRATE_16,
    sample_rate=stt.AudioSampleRates.SAMPLERATE_16000,
    channel=stt.AudioChannels.CHANNELS_1,  # what Whisper-style engines expect
)

Defensive patterns

Strategy: validation

Validate before calling

from homeassistant.components import stt
provider = stt.async_get_speech_to_text_engine(hass, pipeline.stt_engine)
if provider is not None and not provider.check_metadata(metadata):
    _LOGGER.warning("Metadata %s unsupported by %s", metadata, provider.name)

Try / catch

from homeassistant.components.assist_pipeline.error import SpeechToTextError
try:
    await pipeline_job.run()
except SpeechToTextError as err:
    if err.code == "stt-provider-unsupported-metadata":
        # fix audio format or pick another provider
        ...

Prevention

Standardize satellite audio on 16 kHz / 16-bit / mono PCM unless the engine declares otherwise.
Cross-check provider.supported_metadata before opening the stream.
Pin pipeline.stt_language to languages the engine supports.

When it happens

Trigger: Starting a run at the STT stage with stt_metadata whose format (e.g. 8 kHz or 24-bit audio) or language is outside what the selected STT engine supports, so stt_provider.check_metadata(metadata) returns False.

Common situations: A satellite streaming audio at an unusual sample rate to a Whisper engine that only accepts 16 kHz 16-bit mono, or setting stt_language to a language the engine does not model.

Related errors

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