MinusZone - KolorsControlNetPatch

Somewhere between "load the ControlNet" and "apply it," Kolors needs a shim. That shim is MZ_KolorsControlNetPatch. It takes a loaded CONTROL_NET and the Kolors model, and returns a patched CONTROL_NET that's actually compatible with the model. Skipping it is how you get the classic complaint from anyone who tried Kolors ControlNet in 2024: "All my images are coming out looking like junk." The loader alone isn't enough - this node is the reason a ControlNet workflow works at all.

Why Kolors needs a patch at all

Kolors' ControlNets were trained against the Kolors UNet, which has two special components a stock ControlNet doesn't know about: an encoder_hid_proj (the 4096→2048 linear that projects text embeddings before cross-attention) and a label embedding. A ControlNet loaded generically doesn't have either wired up, so the conditioning it injects is misaligned with what the UNet expects. The patch fixes that in two directions:

• It grafts the Kolors model's encoder_hid_proj onto the controlnet, and rewrites its forward pass so the projected context flows through.
• It swaps the controlnet's label embedding for the one from the loaded Kolors model.

The node handles both ControlNet flavors - the ControlLora format and the plain ControlNet format - each with its own patching path, and it deep-copies the controlnet so your original stays untouched. The output, CONTROL_NET, is what you feed the Apply ControlNet node.

Inputs and outputs

• control_net - a CONTROL_NET from MZ_KolorsControlNetLoader (or any loaded controlnet).
• model - your loaded Kolors MODEL; the patch reads the projection and label embedding from it.
• Output: CONTROL_NET → Apply ControlNet → KSampler.

The workflow shape

Load Kolors UNet → MZ_KolorsControlNetLoader → MZ_KolorsControlNetPatch (both the controlnet and the model go in) → Apply ControlNet → KSampler. It's a small, mandatory detour, and it's the piece most ported SDXL ControlNet workflows forget. The pack removed the old automatic compatibility layer on 2024-07-14 specifically to force this explicit step.

Install and common issues

Standard pack install: ComfyUI Manager search "ComfyUI-Kolors-MZ", or git clone https://github.com/MinusZoneAI/ComfyUI-Kolors-MZ into custom_nodes, restart. The node needs no model files of its own - it just needs both inputs wired. The one real gotcha: it expects a Kolors-family model on the model input. Feed it a generic SDXL model and the patch will copy over mismatched weights and produce exactly the junk it's supposed to prevent. If outputs still look broken after patching, check that you loaded the official Kwai-Kolors ControlNet files, not an SDXL controlnet.