unslothai/unsloth · error · SttLanguageError

Language '{language}' is not supported by STT model '{model_

Error message

Language '{language}' is not supported by STT model '{model_id}'.

What it means

Raised by the STT sidecar's transcribe path when an explicitly requested language, after normalization to a Whisper short code (e.g. 'en-US' -> 'en'), is not in Whisper's known language set. The check runs before model download and audio decode, so it fires fast and cheap. It exists because Whisper can only transcribe its ~99 trained languages; anything else would fail or hallucinate inside generation.

Source

Thrown at studio/backend/core/inference/stt_sidecar.py:1673

    ) -> dict:
        """Transcribe encoded audio bytes to text.

        Accepts any container PyAV can decode: wav, mp3, opus/webm, ogg,
        m4a/aac. Returns {text, language, duration, model}.
        """
        # Reject a missing runtime up front, before the cache and bounded decode.
        ensure_stt_available()
        if cancel_event is not None and cancel_event.is_set():
            raise SttTranscriptionCancelledError("Transcription cancelled.")
        # A set language beats auto-detect. API takes BCP-47; Whisper wants short
        # codes like en or fr.
        lang = normalize_whisper_language(language)
        # Pin the requested id: another request may switch the resident model
        # mid-transcription, so sidecar state is not this request's identity.
        model_id = resolve_model_id(model)
        known_languages = _known_whisper_languages()
        if lang is not None and known_languages is not None and lang not in known_languages:
            raise SttLanguageError(
                f"Language '{language}' is not supported by STT model '{model_id}'."
            )
        cached = self._ensure_model_downloaded(model_id)
        if cached.is_multilingual is False and lang not in (None, "en"):
            raise SttLanguageError(
                f"Language '{language}' is not supported by English-only STT model '{model_id}'."
            )
        decoded_audio = _decode_audio_bounded(audio, cancel_event)
        if cancel_event is not None and cancel_event.is_set():
            raise SttTranscriptionCancelledError("Transcription cancelled.")
        # condition_on_prev_tokens=False stops a fresh clip inheriting prior
        # context, which causes runaway repeats.
        generate_kwargs = {
            "task": "transcribe",
            "condition_on_prev_tokens": False,
            "num_beams": 5,
        }
        if lang is not None:

View on GitHub (pinned to 203007d190)

Solutions

Pass a language Whisper supports, preferably the short code ('en', 'fr', 'de') or a BCP-47 tag that normalizes to one.
Omit language (pass None) to let Whisper auto-detect the spoken language.
Validate the value against the tokenizer's language set (or core.inference.stt_sidecar._known_whisper_languages()) before calling transcribe.

Example fix

# before
transcribe(audio, language='eng')  # not a Whisper code

# after
transcribe(audio, language='en')   # Whisper short code
# or omit for auto-detect:
transcribe(audio, language=None)

Defensive patterns

Strategy: validation

Validate before calling

from core.inference.stt_sidecar import normalize_whisper_language, _known_whisper_languages

def is_supported_stt_language(language):
    lang = normalize_whisper_language(language)
    known = _known_whisper_languages()
    return lang is None or known is None or lang in known

Type guard

def valid_whisper_language(language: str | None) -> bool:
    lang = normalize_whisper_language(language)
    known = _known_whisper_languages()
    return lang is None or known is None or lang in known

Try / catch

from core.inference.stt_sidecar import SttLanguageError
try:
    text = stt.transcribe(audio, language=lang)
except SttLanguageError as e:
    # fall back to auto-detect; the language is unusable, not the audio
    text = stt.transcribe(audio, language=None)

Prevention

Constrain language pickers to the BCP-47 subset Whisper actually supports.
Normalize through normalize_whisper_language client-side so validation matches the backend's mapping.
Default to None (auto-detect) when the source of the language string is untrusted.

When it happens

Trigger: Calling transcribe(..., language='xx') where normalize_whisper_language maps the BCP-47 tag to a code absent from _known_whisper_languages(), while a Whisper family model is the target. Only fires when the known-language set is available (not None) and language is not None.

Common situations: Passing a macro-language tag Whisper does not train (e.g. 'cn', 'zz', invented codes); passing a locale Whisper maps to nothing; a UI dropdown seeded with ISO-639-3 codes instead of the BCP-47 subset Whisper supports; a typo like 'eng' instead of 'en'.

Related errors

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/3426a17d779b5396. Report an issue: GitHub.