Comfy-Org/ComfyUI · error · ValueError

MiniMax Music3 text encoder checkpoint is missing tokenizer_

Error message

MiniMax Music3 text encoder checkpoint is missing tokenizer_json

What it means

The MiniMax Music3 text encoder, like several ComfyUI bundled encoders, embeds its HuggingFace tokenizers JSON as a byte blob under 'tokenizer_json' in the checkpoint. MiniMaxMusic3Tokenizer.__init__ raises when tokenizer_data lacks that key, i.e. the checkpoint in models/text_encoders was not the ComfyUI-packaged bundle.

Source

Thrown at comfy/text_encoders/minimax_music.py:41

    "decoder_intermediate_size": 6144,
    "decoder_num_layers": 4,
}


def detect_merged_config(state_dict, prefix=""):
    return {
        "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)),
        }

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Download/use the ComfyUI-packaged MiniMax Music3 text encoder bundle that embeds tokenizer_json
2. Check the checkpoint: safetensors.torch.load_file(path).keys() must include 'tokenizer_json'; if missing, re-bundle
3. When re-bundling, store tokenizer.json bytes as a tensor under 'tokenizer_json' rather than shipping a side file

Example fix

// before
sd = safetensors.torch.load_file("minimax_music3_te_raw.safetensors")  # no tokenizer_json

# after
# bundle: torch.save({'tokenizer_json': torch.frombuffer(open('tokenizer.json','rb').read(), dtype=torch.uint8), ...})
sd = safetensors.torch.load_file("minimax_music3_te_comfy.safetensors")
assert sd.get('tokenizer_json') is not None

sd = safetensors.torch.load_file(te_path)
if sd.get('tokenizer_json') is None:
    raise ValueError(f'{te_path} is not a ComfyUI-packaged Music3 encoder (no tokenizer_json)')

When it happens

Trigger: Instantiating MiniMaxMusic3Tokenizer with tokenizer_data that has no 'tokenizer_json' entry — loading raw MiniMax Music3 HF weights converted by a generic converter instead of the ComfyUI bundle script.

Common situations: User downloaded the original HF repo weights directly instead of the ComfyUI-packaged safetensors; a conversion script filtered out non-float tensors, dropping the tokenizer blob.

Related errors

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

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