Comfy-Org/ComfyUI · error · ValueError

MiniMax Music3 tokenizer mismatch for {token}

Error message

MiniMax Music3 tokenizer mismatch for {token}

What it means

After loading the embedded tokenizer JSON, MiniMaxMusic3Tokenizer validates that the special tokens (from SPECIAL_TOKEN_IDS, e.g. audio/lyrics boundary tokens) map to the exact IDs the model was trained with. If any token_to_id lookup disagrees, the vocabulary does not match the model's embedding table, so token IDs would index wrong rows and silently corrupt conditioning — hence a hard failure naming the offending token.

Source

Thrown at comfy/text_encoders/minimax_music.py:48

        "merged_qkv": "{}model.layers.0.self_attn.qkv_proj.weight".format(prefix) in state_dict,
        "merged_mlp": "{}model.layers.0.mlp.gate_up_proj.weight".format(prefix) in state_dict,
        "decoder_merged_qkv": "{}model.audio_decoder.layers.0.self_attn.qkv_proj.weight".format(prefix) in state_dict,
        "decoder_merged_mlp": "{}model.audio_decoder.layers.0.mlp.gate_up_proj.weight".format(prefix) in state_dict,
    }


class MiniMaxMusic3Tokenizer:
    def __init__(self, embedding_directory=None, tokenizer_data={}):
        tokenizer_json = tokenizer_data.get("tokenizer_json")
        if tokenizer_json is None:
            raise ValueError("MiniMax Music3 text encoder checkpoint is missing tokenizer_json")
        if torch.is_tensor(tokenizer_json):
            tokenizer_json = tokenizer_json.detach().cpu().numpy().tobytes()
        self.tokenizer_json = tokenizer_json
        self.tokenizer = Tokenizer.from_str(tokenizer_json.decode("utf-8"))
        for token, expected in SPECIAL_TOKEN_IDS.items():
            if self.tokenizer.token_to_id(token) != expected:
                raise ValueError(f"MiniMax Music3 tokenizer mismatch for {token}")

    def tokenize_with_weights(self, text, return_word_ids=False, **kwargs):
        prompt = build_prompt(text, kwargs.get("lyrics", ""))
        token_ids = self.tokenizer.encode(prompt, add_special_tokens=False).ids
        return {
            "minimax_music3": [[(token, 1.0) for token in token_ids]],
            "seed": int(kwargs.get("seed", 0)),
            "max_audio_frames": int(kwargs.get("max_audio_frames", MAX_AUDIO_FRAMES)),
            "cfg_scale": float(kwargs.get("cfg_scale", CFG_SCALE)),
            "top_k": int(kwargs.get("top_k", CFG_TOP_K)),
        }

    def state_dict(self):
        return {"tokenizer_json": torch.frombuffer(bytearray(self.tokenizer_json), dtype=torch.uint8)}

    def decode(self, token_ids, skip_special_tokens=True):
        return self.tokenizer.decode(token_ids, skip_special_tokens=skip_special_tokens)

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Use the exact tokenizer.json that ships with the same MiniMax Music3 release as the model weights
2. Re-bundle the encoder with bundle_te.py from the matching commit so tokenizer and weights stay paired
3. If maintaining a fork, diff the failing token's ID between tokenizer.json and SPECIAL_TOKEN_IDS and align them

Example fix

// before
# bundled with tokenizer.json from a different Music3 revision
tok = MiniMaxMusic3Tokenizer(tokenizer_data=sd)  # ValueError: mismatch for <token>

# after
# re-bundle with the tokenizer.json from the same release as the weights
assert tok.tokenizer.token_to_id('[audio]') == EXPECTED_ID  # guard before use

from tokenizers import Tokenizer
import json
tok = Tokenizer.from_str(json.loads(open('tokenizer.json').read()) if False else open('tokenizer.json').read())
for token, expected in SPECIAL_TOKEN_IDS.items():
    if tok.token_to_id(token) != expected:
        raise ValueError(f'tokenizer/weights revision mismatch at {token}')

When it happens

Trigger: tokenizer_data['tokenizer_json'] contains a tokenizer.json whose vocabulary differs from the one the MiniMax Music3 model was trained with (different merges, added tokens, or version), so token_to_id(token) != expected for a token in SPECIAL_TOKEN_IDS.

Common situations: User re-bundled the encoder with a tokenizer.json from a different revision of the MiniMax repo; mixing tokenizer files between Music3 variants; hand-edited vocab files.

Related errors

• MiniMax Music3 text encoder checkpoint is missing tokenizer_
• MiniMax Music3 prompt has {prompt_tokens} tokens; maximum is
• MiniMax Music3 tokenizer mismatch for {token}: expected {exp
• MiniMax Music3 generated zero audio frames
• Lens tokenizer requires the ``tokenizer_json`` byte tensor i

AI-assisted analysis of Comfy-Org/ComfyUI@1c6d8d45b3 (2026-08-14). Data as JSON: /api/errors/187b8eb93fd6ccce. Report an issue: GitHub.