sgl-project/sglang · critical · ValueError

tokenizer missing required special token {name!r}; checkpoin

Error message

tokenizer missing required special token {name!r}; checkpoint vocab does not match MiMo-V2-ASR

What it means

Raised by _resolve_special_token_id in the MiMo-V2-ASR pipeline when the tokenizer's convert_tokens_to_ids returns None or the unk token for a required special token. This means the loaded checkpoint's vocabulary doesn't contain the ASR-specific special tokens, i.e. you're pointing MiMo-V2-ASR code at a non-ASR (base) checkpoint.

Source

Thrown at python/sglang/srt/multimodal/processors/mimo_v2_asr.py:86

        self.mm_tokens = MultimodalSpecialTokens(
            audio_token=f"{self.AUDIO_START_TOKEN}{self.AUDIO_PAD_TOKEN}{self.AUDIO_END_TOKEN}",
            audio_token_id=self.audio_token_id,
            audio_token_regex=self.AUDIO_REGEX,
        ).build(_processor)

    def __getattr__(self, name):
        # Delegate audio_pipeline fields so callers can use self.audio_token_id
        # etc. directly. Only triggers when normal attribute lookup fails;
        # __dict__.get avoids recursion before audio_pipeline is assigned.
        pipeline = self.__dict__.get("audio_pipeline")
        if pipeline is not None and hasattr(pipeline, name):
            return getattr(pipeline, name)
        raise AttributeError(name)

    def _resolve_special_token_id(self, name: str) -> int:
        tid = self.tokenizer.convert_tokens_to_ids(name)
        if tid is None or tid == self.tokenizer.unk_token_id:
            raise ValueError(
                f"tokenizer missing required special token {name!r}; "
                "checkpoint vocab does not match MiMo-V2-ASR"
            )
        return int(tid)

    def _process_contents(self, contents: List[_Content]):
        """Run pipeline + tokenizer over an interleaved content list.

        Returns ``(input_ids: Tensor[L], audio_inputs: list[Tensor],
        position_ids: Tensor[3,L], rope_deltas: Tensor[1,1])``.
        """
        input_ids: List[int] = []
        audio_inputs: List[torch.Tensor] = []

        for content in contents:
            if content.type == "text":
                if isinstance(content.content, str):
                    input_ids.extend(self.tokenizer.encode(content.content))

View on GitHub (pinned to 0132848349)

Solutions

1. Use the correct MiMo-V2-ASR checkpoint and its bundled tokenizer files
2. Clear the HF cache for the mismatched revision and re-download the ASR repo
3. Verify: tokenizer.convert_tokens_to_ids('<asr_token>') should not be None/unk before init

Example fix

# before
model = 'org/MiMo-V2'            # base vocab → ValueError
# after
model = 'org/MiMo-V2-ASR'        # checkpoint whose vocab contains ASR specials

tok = tokenizer
for name in REQUIRED_SPECIALS:  # e.g. ['<|asr_start|>', '<|asr_end|>', ...]
    tid = tok.convert_tokens_to_ids(name)
    assert tid is not None and tid != tok.unk_token_id, \
        f'checkpoint vocab lacks {name}; use the MiMo-V2-ASR checkpoint'

try:
    pipeline = MiMoV2ASRPipeline(model_path, tokenizer)
except ValueError as e:
    if 'checkpoint vocab does not match MiMo-V2-ASR' in str(e):
        raise ConfigError('point --model-path at the MiMo-V2-ASR repo, not the base model')
    raise

When it happens

Trigger: Initializing the MiMo-V2-ASR processor with a tokenizer from the base MiMo-V2 model (or a mismatched revision) so tokens like the ASR begin/end specials resolve to unk; also when tokenizer.json is from an older vocab version.

Common situations: Downloading the base model repo instead of the -ASR variant; reusing a cached tokenizer from a different model revision; vocab updates in the model family between releases.

Related errors

• Ring Attention requires a backend whose kernel exposes the s
• Cannot load PE model: 'model_max_length' not found in {os.pa
• Reference attention was not initialized.
• Multiview attention was not initialized.
• Expected BasicTransformerBlock, got {type(transformer).__nam

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