Apply Qwen Image 2.1 UNION

You preprocessed a pose skeleton, a depth map, or a canny map, and now you want Qwen Image 2.1 to render something that actually obeys it. Apply Qwen Image 2.1 UNION is where that obedience gets attached to your sampler. It takes the diffusion model, the Union patch, your map, and hands the whole thing back as a MODEL you sample normally.

First thing to get straight, because it trips people up: control_mode does not change how the node behaves. The Union checkpoint has no mode embedding - it just reads the pixels you give it. The dropdown is validated against eight labels (Canny, Depth, Grayscale, HED, Lineart, MLSD, Pose, Scribble), and the author says it plainly in the node description: the mode labels the map, the model reads the pixels. So a depth map run through the "Canny" setting still works. It's documentation for your graph, not a switch. Pick the honest one anyway; six months from now you'll be glad you did.

How it works

This is ControlNet in its 2026 shape. On DiT architectures like Qwen-Image there's no UNet encoder to copy, so the condition is re-implemented as a patch over attention and MLP layers - which is why the loader hands you a MODEL_PATCH and this node takes a MODEL plus that patch plus… a VAE. That last one is the tell: the node VAE-encodes your control image (and inpaint image, and mask) into the latent space the model actually attends over, then calls ComfyUI's native Qwen Image 2.1 Fun apply path. You don't wire a separate encode step. And it isn't a reimplementation of anything - it's a thin, well-guarded wrapper over upstream code, which is the right way to ship a node like this.

The inputs that matter

• strength defaults to 1.0 in the pack. Modern unions generally publish lower working values - Alibaba PAI's FLUX.2 union asks for 0.65-0.80 and the older InstantX Qwen union 0.8-1.0 - so treat 1.0 as "the card doesn't argue with you" and try 0.7-0.8 first if your output is fighting the prompt.
• start_percent / end_percent are the real precision dial, and the one most people never touch. Ending the condition at 0.5-0.6 lets ControlNet form the composition and then hands the last third of the sample back to the model to add its own detail. Holding 0→1 gives the strictest adherence and the stiffest pictures.
• control_image, inpaint_image, mask - optional individually, and each must carry exactly one image. The node raises a clear error if you connect a batch, because the native path silently uses only the first frame. For inpainting, connect the source image and a mask where white is regenerated; connecting inpaint_image without a mask is an error, which is the right call.
• union_patch comes from Load Qwen Image 2.1 UNION. model comes from your UNETLoader, vae from the 2.1 VAE.

The single output is MODEL - wire it into KSampler exactly where you'd normally put the loader's model.

Install

Through ComfyUI Manager search for Qwen Image 2.1 Fun ControlNet Union (T8), or:

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

There are no Python dependencies - pyproject.toml lists an empty dependency set - but the pack needs a ComfyUI build with native Qwen Image 2.1 Fun support (upstream PR #16519 or a release containing it), plus three files besides the union checkpoint: the Qwen 2.1 diffusion model, the Qwen3-VL 8B text encoder, and the VAE, all placed per the README's table (models/diffusion_models, models/text_encoders, models/vae, union in models/controlnet). The pack also ships nine ready workflows and sample inputs under assets/; the .api.json ones are API prompts, not canvas files.

Heads up on licensing: node code is MIT, but the Qwen 2.1 Fun weights are under the Qwen Research License - non-commercial unless you license separately. Same footing as other Alibaba PAI Fun unions.

Where people get burned

• The mode dropdown being empty isn't this node's fault - that's the loader finding no matching file in models/controlnet/.
• Wrong order of the sliders: start_percent above end_percent is a hard error, not a silent no-op.
• Ultra-wide control inputs get rejected once a computed output side would pass 4096px. Crop or pad.
• CFG 7 habits. Qwen 2.1 is LLM-encoded and guidance-distilled; the shipped workflows run cfg: 1.0 with 40 steps and no negative prompt. At CFG 1 the negative is never even computed, so a wall of "blurry, deformed, bad anatomy" does nothing - restate it as a positive constraint instead. Same for (word:1.4) weighting, which the encoder reads as literal punctuation.