FL Z-Image ControlNet Patch Loader

Z-Image got ControlNet support fast by 2026 standards - Alibaba's own PAI team (a different sub-team from the Tongyi-MAI lab that trained Z-Image itself) shipped a Union ControlNet within about a week of each Z-Image release, covering canny, depth, pose, and a handful of other conditions, with separate versions for Turbo and Base. But Z-Image is a DiT model, not the old UNet architecture ControlNet was originally built for - on a DiT, "ControlNet" gets re-implemented as a patch against attention and MLP layers rather than a duplicated encoder bolted onto the side. FL_ZImageControlNetPatch is a loader for exactly that kind of patch. It's the one node in this batch actually marked EXPERIMENTAL = True in the pack's own source and filed under Work-in-Progress, so treat it accordingly: useful, but expect rough edges.

How it works

You point it at a ControlNet patch checkpoint on disk (something trained against Z-Image's architecture - or, per the node's own display name, the related Lumina model family) and it loads it as a MODEL_PATCH object, which you'd then feed into whatever apply-node your workflow uses to attach that behavior onto your loaded Z-Image model. auto_config (on by default) tries to read the checkpoint's own structure and set the patch parameters correctly without you touching anything. The three optional parameters exist for the case where auto-detection guesses wrong or you're loading a checkpoint the auto-config logic doesn't recognize - the README calls them out explicitly as for "manual tuning."

The inputs and outputs that matter

• name - a dropdown of ControlNet patch checkpoint files available on disk. If it's empty, you haven't placed a compatible checkpoint in the folder this node scans yet; that's the checkpoint you'd download from a source like Alibaba PAI's Z-Image Fun-Controlnet-Union releases (or a compatible third-party Lumina-family patch).
• auto_config (BOOLEAN, default true) - leave this on for any normal checkpoint from a known source. It's reading the checkpoint's own metadata/shape to infer the three settings below rather than making you guess them.
• n_control_layers (INT, default 6, range 1–30, optional) - how many of the model's transformer blocks the patch touches. Only relevant with auto_config off.
• additional_in_dim (INT, default 17, range 0–64, optional) - how many extra input channels the conditioning signal adds beyond the base latent. Also only relevant with auto_config off.
• refiner_control (BOOLEAN, default false, optional) - whether the patch also applies during a refiner pass, for workflows that use one.

One output: MODEL_PATCH.

How to install it

Via ComfyUI Manager: search ComfyUI_Fill-Nodes (or Fill-Nodes), install, restart. Or manually:

cd ComfyUI/custom_nodes
git clone https://github.com/filliptm/ComfyUI_Fill-Nodes

The node itself installs with no extra downloads, but it's useless without an actual ControlNet patch checkpoint compatible with Z-Image's architecture placed in the right models folder - the node loads local files, it doesn't fetch anything for you.

Common issues & troubleshooting

The name dropdown is empty. No compatible checkpoint file is where this node expects it. Download an actual Z-Image (or Lumina-family) ControlNet patch - Alibaba PAI's Fun-Controlnet-Union releases are the well-supported, first-party option for Z-Image specifically - and restart or refresh ComfyUI so the loader picks it up.

It's flagged experimental for a reason. This node ships under Work-in-Progress with EXPERIMENTAL = True set in the source. Don't build a production pipeline around it without testing it against your specific model and checkpoint combination first; behavior may change between pack updates.

Shape-mismatch errors when the patch is applied. If you loaded a checkpoint that isn't actually trained for the Z-Image/Lumina architecture - or auto_config guessed wrong on an unusual, non-standard checkpoint - the downstream apply step is the place you'll see it break, usually as a tensor shape mismatch. That's the case to flip auto_config off and set n_control_layers / additional_in_dim to match what the checkpoint was actually trained with, if you know those numbers.

Applying it to a base model that isn't Z-Image/Lumina. This patch format is specific to that architecture family - it won't do anything sensible loaded against SDXL, Flux, or Qwen-Image checkpoints, which each have their own, differently-shaped ControlNet ecosystems.