sgl-project/sglang · error · ValueError

Language '{language}' is not in this Whisper model's vocabul

Error message

Language '{language}' is not in this Whisper model's vocabulary. The '{language_token}' token may have been added in a later Whisper version than the loaded checkpoint.

What it means

Whisper language tokens (e.g. '<|zh|>') were added incrementally across Whisper releases. When the loaded checkpoint's tokenizer maps the token to unk or None, the processor raises this clean ValueError instead of silently decoding garbage. It means the language is valid Whisper-wise but newer than the checkpoint's vocabulary.

Source

Thrown at python/sglang/srt/multimodal/processors/whisper.py:159

    def _pop_sampling_param(self, request_obj, key: str):
        sampling_params = getattr(request_obj, "sampling_params", None) or {}
        return sampling_params.pop(key, None)

    def _get_language_token_id(self, language: Optional[str]) -> int:
        # Default to English if not specified
        if language is None:
            language = "en"  # Default to English
        language_token = f"<|{language}|>"
        token_id = self._tokenizer.convert_tokens_to_ids(language_token)
        # normalize_language_to_code accepts the full Whisper language-token
        # vocab (including yue/haw/jw) so fused autodetect output round-trips.
        # Older checkpoints (v1/v2) don't have every newer token in their
        # vocab, in which case convert_tokens_to_ids returns the unk id.
        # Raise a clean error here instead of silently feeding unk into the
        # decoder and producing garbage.
        unk_id = getattr(self._tokenizer, "unk_token_id", None)
        if token_id is None or (unk_id is not None and token_id == unk_id):
            raise ValueError(
                f"Language '{language}' is not in this Whisper model's vocabulary. "
                f"The '{language_token}' token may have been added in a later "
                f"Whisper version than the loaded checkpoint."
            )
        return token_id

    async def process_mm_data_async(
        self,
        image_data,
        audio_data,
        input_text,
        request_obj,
        **kwargs,
    ) -> Optional[Dict[str, Any]]:
        if not audio_data:
            return None

        if len(audio_data) != 1:

View on GitHub (pinned to 0132848349)

Solutions

1. Use a newer/larger Whisper checkpoint that includes the language token
2. Pick a different language supported by the loaded checkpoint
3. Pin the model version known to contain your required languages

Example fix

# before
model = openai/whisper-small  # older vocab
language = '<newer-language>'
# after
model = openai/whisper-large-v3  # includes newer language tokens

tok = processor._tokenizer
tid = tok.convert_tokens_to_ids(lang_token)
if tid in (None, getattr(tok, 'unk_token_id', None)):
    raise ValueError(f'{lang_token} unavailable in this checkpoint')

When it happens

Trigger: Loading a Whisper v2 checkpoint and requesting a language whose token was only introduced in v3 (token_id is None or equals unk_token_id in _get_language_token_id).

Common situations: Mixing openai/whisper-large-v3 requests against a small/turbo checkpoint; community fine-tunes with trimmed vocabularies; CI upgrading language lists without upgrading weights.

Related errors

• Language '{language}' not recognized. Use full name (e.g., '
• Whisper expects exactly 1 audio input, got {len}
• audio_out_channels must be divisible by tp_size for TP-shard
• audio_num_frames must be provided for RoPE coordinate genera
• sound generation was requested (sound_duration > 0) but the

AI-assisted analysis of sgl-project/sglang@0132848349 (2026-08-28). Data as JSON: /api/errors/d1be18f96fcda251. Report an issue: GitHub.