H3 Fun ControlNet Loader

The first thing you'll hit when you try to ControlNet MiniMax-H3 is that the obvious file - the official one from Alibaba PAI - doesn't load. That's not you, and it's not a broken install. It's a genuine weights mismatch, and this loader is the node that explains it instead of loading garbage and failing weirdly ten steps later.

H3FunControlLoader does one job: read a MiniMax-H3 Fun-ControlNet checkpoint out of models/controlnet and hand it to the Apply node. It takes a single control_net_name dropdown (every file in that folder) and outputs a control_net in the custom H3_FUN_CONTROL type, which plugs straight into H3FunControlApply's control_net input. That's the whole interface. The substance is in which file it will accept.

Why the official weights don't work

H3 ships in two flavors. The pruned checkpoints almost everyone actually runs - Kijai's MiniMax-H3-experimental - replace roughly 40% of the modulation weights with a lookup table built from a fitted curve. That's the "curve-form" basis, and its AdaLN projection is [96768, 8]. Alibaba PAI's original MiniMax-H3-Fun-Controlnet-Union release is full-width AdaLN, [96768, 2688] - designed for the 34 GB non-pruned base. The two don't line up, so the official ControlNet is effectively unusable for the models people run.

Kijai then re-derived the ControlNet into the curve-form basis, using ComfyUI's own module naming (the checkpoint carries metadata {"minimax_h3_fun_controlnet": "adaln_basis"}). That's the file this node targets: minimax_h3_fun_controlnet_union_pruned_bf16.safetensors, from the same Kijai repo. The loader peeks at control_blocks.0.adaln_proj.linear.weight and, if the last dimension isn't 8, raises a clear error telling you you grabbed the full-width release and to use the pruned/adaln_basis file. No guessing, no silent corruption - it's the one node in the pack that fails loudly and helpfully.

Mechanically it's a thin wrapper: safe_load the torch file, validate, then build the tower - five blocks that are literally ComfyUI's own DiTBlock plus a zero-gated skip projection, all loading strict=True. It also freezes the weights (eval(); requires_grad_(False)), because H3's attention uses a fused in-place RoPE kernel that refuses any tensor carrying autograd. If you ever see "in-place RoPE operations are inference-only", the fix is already in here.

Install

No dependencies beyond ComfyUI itself - the node is built out of comfy.ldm.minimax, which means you need ComfyUI 0.34.0 or newer (that's when those modules landed). CUDA-only, tested on an RTX 5090.

cd ComfyUI/custom_nodes
git clone https://github.com/wyzborrero/ComfyUI-H3-FunControl

Or find ComfyUI-H3-FunControl in ComfyUI Manager. Restart ComfyUI after installing.

Then download the checkpoint into the right folder:

# from https://huggingface.co/Kijai/MiniMax-H3-experimental
# file: minimax_h3_fun_controlnet_union_pruned_bf16.safetensors
mv minimax_h3_fun_controlnet_union_pruned_bf16.safetensors ComfyUI/models/controlnet/

Troubleshooting

• "has full-width AdaLN (t_dim=2688) ... will not load" - you have the official Alibaba PAI release. Delete it and grab Kijai's pruned file above. This is the number one way people burn an hour on H3 control.
• Empty dropdown - the file isn't in models/controlnet (or ComfyUI hasn't rescanned; restart if you dropped it in while running).
• Node edits have no effect - custom nodes are imported once at startup. The author's README says this cost them a whole experiment. Restart, always.
• control_net_name missing from your saved workflow - you likely moved/renamed the checkpoint. Point it at the file again.

One licensing note, because it's load-bearing for the whole H3 ecosystem: the H3 base weights ship under the MiniMax H3 Community License, which excludes the US, EU, UK and South Korea from running them locally. If you're in one of those regions, the control adapter is the least of your problems - check whether you're allowed to run the base model at all.

It's a tiny node, and that's fine. The value is that it only loads the file that can actually work, and tells you why when you hand it the one that can't.