MiniMax H3 Diffusers LoRA Convert

The symptom this node exists for

You grabbed a MiniMax H3 LoRA off HuggingFace, dropped it in models/loras, wired the usual loader, hit queue - and the output is the same video you would have got without it. No red error. Nothing "failed". That silence is the clue.

ComfyUI matches LoRA tensors to model tensors by name. When names don't line up, it skips what it can't place and carries on with whatever it matched - which is why the result feels slightly off at best and identical at worst. Same wall people hit with Z-Image Turbo, where a diffusers-format LoRA loads without complaint and patches nothing, because the model wants a fused qkv projection and the LoRA has separate to_q/to_k/to_v. H3 has the same mismatch with more moving parts, and it's structural: H3 LoRAs get trained in diffusers/PEFT land, where the training tooling lives, while ComfyUI runs the model in its own native layout. H3 landed in August 2026 as a 33B omni-modal video model with day-zero ComfyUI support, so practically every H3 LoRA you'll find is a diffusers adapter. This node is the translator.

What the conversion actually does

It streams through the LoRA with unifiedefficientloader and rewrites three things.

First, names. Diffusers modules get mapped onto ComfyUI's: transformer_blocks.4.attn.to_q becomes diffusion_model.blocks.4.attn.qkv_proj, token_refiner.refiner_blocks.N.* lands under diffusion_model.token_refiner.blocks.N.*, and the odds and ends get homes - ff.net.0.proj → mlp.fc1, ff.net.2 → mlp.fc2, attn.to_out.0 → attn.out_proj.

Second, QKV fusion. The three separate attention adapters become one qkv_proj pair: down matrices concatenated vertically, up matrices dropped into a block-diagonal arrangement. That's exact concatenation, not an approximation - no SVD, no rank guessing, nothing thrown away in the QKV step.

Third, SwiGLU ordering. Diffusers stores the MLP projection's output halves as [value; gate]; ComfyUI wants [gate; value]. The node swaps them. Get that wrong and the LoRA loads and emits garbage, which is worse than not loading.

Output is written as target.lora_A.weight / target.lora_B.weight pairs - a normal ComfyUI LoRA - with metadata tags recording what was done. It refuses anything it can't account for rather than half-converting: an incomplete A/B pair, mismatched rank, duplicate factors, or an unrecognised module tail all raise a specific error naming the key. Read that message; it usually means the file isn't an H3 PEFT LoRA at all.

The two inputs and two outputs

Only two inputs matter, and they're both required.

lora_name is the diffusers-format H3 LoRA, picked from a dropdown of whatever is in ComfyUI's LoRA folder. If your LoRA isn't in that folder, it isn't in that dropdown.

output_filename is just a name - no folder, no extension (one gets appended if you add it). Defaults to minimax_h3_comfyui and lands under ComfyUI's LoRA directory.

The outputs are output_path, which hands back the written file's name inside the LoRA folder, and conversion_report: a short text report with tensors in, tensors out, how many QKV modules were fused, file size and final path. Glance at it - if "fused QKV modules" is zero, your LoRA had no attention adapters in it. This is an output node, so it runs as a terminal action; nothing to wire it into.

Installing it

The pack publishes to the Comfy Registry as Model Utility Toolkit, so ComfyUI Manager can find it by that name or by ComfyUI-ModelUtils. Manual route:

cd ComfyUI/custom_nodes
git clone https://github.com/silveroxides/ComfyUI-ModelUtils
cd ComfyUI-ModelUtils && pip install -r requirements.txt

requirements.txt pulls unifiedefficientloader>=0.5.2 - the streaming safetensors reader the whole pack is built on - plus requests, Pillow, mutagen and av (PyAV, used by the pack's downloader nodes). The node imports comfy_api.latest, so it needs a reasonably current ComfyUI; on an older build the pack fails to import before you ever see a node.

One quirk: the README's feature list doesn't mention the MiniMax H3 nodes at all - it stops at MetaKeys, RenameKeys and mergers. Search the node menu, not the docs.

Where people get burned

• HuggingFace repos are folders, not files. A PEFT adapter download is adapter_model.safetensors plus a config inside a directory. The .safetensors has to sit directly in ComfyUI/models/loras before lora_name can offer it. This is the number one cause of "the node can't see my LoRA".
• Quantized or low-bit input. The pack runs a low-bit guard and bails on fp8/int8 tensors and quant sidecars instead of silently producing a broken merge. Convert the full-precision original.
• The output can't be the input. Same-path writes are rejected outright - it's a streaming rewrite.
• Post-conversion sanity check. The pack also ships LoRA MetaKeys, which dumps tensor keys from a LoRA file. Compare the converted file to a native H3 LoRA: qkv_proj entries present, ff.net.* names gone.
• A converted file that still feels weak is probably a weak LoRA. The rewrite is lossless, so if it underperforms, that's a training question. Rank and alpha don't port across architecture boundaries, so "same settings as my SDXL LoRA" isn't a useful baseline here. And since H3 is new, expect thin community reporting rather than a pile of war stories - the mechanics above come from the shipped code, not from consensus.