InstantX Flux Union ControlNet Loader

First thing you need to know: this node is deprecated, and the author says so in the README. If you've landed here on a current ComfyUI install, the honest advice is to skip the custom node entirely and use the native support for the InstantX/Shakker Labs Union ControlNet Pro instead - ComfyUI ships it now, and it produces higher quality output than the alpha this loader was built for. But this loader has a story, and it explains why Flux ControlNet tooling looks the way it does today.

Back in August 2024, this was the way to run a union ControlNet on FLUX.1 dev in ComfyUI. Its author (Eero Heikkinen, "eesahe" on Reddit) ported InstantX's controlnet code into ComfyUI, published the pack, and his companion pull request landed in ComfyUI core. That original Reddit post - "Union Flux ControlNet running on ComfyUI," +276, 140 comments - is where half the Flux community first learned what a union model even was.

What it actually does

A "union" ControlNet is one checkpoint that handles many condition types instead of a separate model per type. The FLUX.1-dev-Controlnet-Union-alpha it targets covers seven modes - canny, tile, depth, blur, pose, gray, lq - in a single ~3.65B-parameter file. That matters because Flux ControlNets weren't all created equal: the XLabs ones of the era had just 2 transformer layers applied to the first two of Flux's 57 transformer layers. InstantX's union reads the condition image as VAE-encoded latents and runs 15 controlnet blocks across all 57 layers. Heavier, yes - and noticeably more robust, which is why people reported depth that "works way better than the standalone controlnets."

Mechanically, the node is a loader plus a mode switch. It builds a Flux-shaped ControlNet architecture on the fly, detects which of two formats the checkpoint uses by sniffing its keys (controlnet_mode_embedder.fc.weight → the alpha build, controlnet_mode_embedder.weight → the format-2 build), and hands you back a standard CONTROL_NET.

The two inputs that matter

The whole node is just two fields:

• control_net_name - a file picker for anything in models/controlnet. Point it at diffusion_pytorch_model.safetensors from InstantX/FLUX.1-dev-Controlnet-Union-alpha.
• type - the enum (canny, tile, depth, blur, pose, gray, lq). This is the mode selector: the loader maps it to a mode number (canny=0 through lq=6) and sets it as the ControlNet's control_type. Pick the one that matches the preprocessing you fed it - canny map means canny, depth map means depth.

The single CONTROL_NET output wires straight into a ControlNetApplyAdvanced node, same as any other ControlNet. Strength and start/end steps live there, not here.

Install

Via ComfyUI Manager (search "ComfyUI-eesahesNodes"), or the old-fashioned way:

cd ComfyUI/custom_nodes
git clone https://github.com/EeroHeikkinen/ComfyUI-eesahesNodes
cd ComfyUI-eesahesNodes
pip install -r requirements.txt

Dependencies are just diffusers>=0.30.0 and einops>=0.7.0 - you almost certainly already have both. Then grab the alpha checkpoint from HuggingFace and drop it in models/controlnet. The model itself is the real cost: loaded at bfloat16 it eats roughly 7GB of VRAM on top of the base Flux stack, and the author's own verdict was that 12GB cards are too tight.

Where people get burned

The classic error is Only InstantX union controlnet supported. Could not find key 'controlnet_mode_embedder.fc.weight'. That's the loader refusing a file that isn't the alpha checkpoint - try pointing it at the non-alpha repo or a Union Pro file and you get exactly this. There was also a stretch where InstantX updated their repo mid-life and briefly broke this loader until the author added format-2 support.

But the real trap is simpler: it's 2026, and you don't need it. If a workflow you copied still references this node, modern ComfyUI's built-in Load ControlNet Model + SetUnionControlNetType pair with the Union Pro 2.0 checkpoint is strictly better - same union idea, better conditioning, no custom node to maintain. Treat this loader as the interesting piece of history it is.