Load Qwen Image 2.1 UNION

One input, one output, and about forty lines of validation that will save you an hour of confusion. Load Qwen Image 2.1 UNION turns the converted Union checkpoint into a MODEL_PATCH - the control tower as a patch you attach to a Qwen Image 2.1 diffusion model, rather than a checkpoint you plug into the old ControlNetLoader slot.

If you've used a modern union before, this is the same idea: one file, eight conditions (Canny, Depth, Grayscale, HED, Lineart, MLSD, Pose, Scribble) plus masked inpainting, no per-condition downloads. That's the 2026 deal - the unions land within days of each base and cover everything you'd realistically reach for, while quietly dropping the old menu (segmentation, normal maps, Reference, QR-pattern brightness) that only SDXL still has. This is Alibaba PAI's Fun union for Qwen Image 2.1, converted to ComfyUI's naming by the pack author.

What it actually does

It does not hand your file to a generic loader. It opens the safetensors header first (capped at 1 MB, with explicit checks for an invalid, oversized, or truncated header), then asserts the file really is this model:

the keys control_img_in.weight and control_blocks.0.img_mlp.out.weight must exist;
control_img_in.weight must be shaped [4096, 129];
there must be exactly 16 control_blocks.N.after_proj blocks, and no 17th.

Fail any of those and you get a sentence, not a stack trace: "This is not a Qwen Image 2.1 Fun Union checkpoint." Only then does it build the native control class - block count, inner dim, attention head dim and MLP ratio all read off the checkpoint - wrap it in a CoreModelPatcher, and load state strictly, raising on missing or unexpected tensors. That strictness is the point: a silently half-loaded control tower produces images that simply ignore your map, which is a much worse afternoon than an error message. The published receipt in MODEL_SHA256.json (180 tensors, 16 blocks) is what the author audited against.

The input, and the trap

union_model is a dropdown populated from models/controlnet/, filtered to files whose names start with Qwen-Image-2.1-Fun-Controlnet-Union and end .safetensors. The output is a single union_patch (type MODEL_PATCH) that goes into the union_patch input of Apply Qwen Image 2.1 UNION.

Because of that name filter, the most common head-scratcher with this node is an empty dropdown: the file is in the wrong folder (models/checkpoints is not models/controlnet), or the browser appended something like (1) or _1 when you downloaded it twice. Rename it back and hit the refresh button next to the dropdown.

Install

ComfyUI Manager → search Qwen Image 2.1 Fun ControlNet Union (T8). Or hand-rolled:

cd ComfyUI/custom_nodes
git clone https://github.com/T8mars/Comfyui-Qwen-Image-2.1-Fun-Controlnet-Union-T8
# restart ComfyUI

The pack itself installs nothing - no Python dependencies at all. What it does need is a ComfyUI new enough to contain the native Qwen Image 2.1 Fun pipeline (upstream PR #16519 or a release with it). Miss that and the node imports fail with a RuntimeError naming exactly that. Then place the four files:

Qwen-Image-2.1-Fun-Controlnet-Union-ComfyUI.safetensors  ->  models/controlnet/
qwen_image_2.1_int8_convrot.safetensors                   ->  models/diffusion_models/
qwen3vl_8b_int8_convrot.safetensors                       ->  models/text_encoders/
qwen_image_2.1_vae_bf16.safetensors                       ->  models/vae/

The union comes from the author's HuggingFace conversion (t8star/Qwen-Image-2.1-Fun-Controlnet-Union-Comfy); the other three from Comfy-Org's Qwen Image 2.1 repo. Those int8_convrot names are the good news for anyone on a 30-series card - INT8-ConvRot is the format ComfyUI adopted natively in v0.27.0, and it's the reason older non-fp8 hardware isn't second-class any more. Copy assets/ into ComfyUI/input/ if you want the shipped workflows to run unmodified.

Licence, because it's easy to miss: the node code is MIT, the weights are Qwen Research License - non-commercial unless Qwen licenses you separately.

Common issues

Empty union_model dropdown - filename or folder, as above.
"This is not a Qwen Image 2.1 Fun Union checkpoint." - you grabbed a different union. The InstantX Qwen-Image union (for the 1.0/2512 line) and the Z-Image or FLUX.2 Fun unions are all different animals; no SD-era ControlNet loads on any DiT base, and no union crosses between architectures.
A mismatch error naming shapes and block counts - the header read fine but the tensors aren't 16 blocks at 4096/129. Usually a partially downloaded or re-exported file. Re-download and check the SHA-256.
Validation passes, sampling ignores your map - that's not the loader. Check batches and mask wiring in the apply node, and check you didn't override strength or end_percent into no-op territory.

One honest note: this pack is new, and the community signal around Qwen Image 2.1 and the T8 author is thin - you're early. The upside is that the README is unusually candid about what runs and what it checked, which is more than most packs manage.