Flux Mask Ref Controller ⚡

A reference image almost never deserves to be copied in full. Maybe you want the model to hold the background of a photo but invent a new subject. Maybe you want the subject but not the busy background bleeding into your edit. Flux Mask Ref Controller is the node that spatial-masks a reference latent - paint a mask over the parts you don't want, and those parts stop influencing the generation.

It's from the ChrisColeTech/ComfyUI-Flux-Reference-Tools pack, and it's the conditioning-side companion to the K/V controllers: they attenuate a reference's strength everywhere, this one attenuates it somewhere - in pixels, not in token space.

How it works

Reference latents in Flux conditioning aren't opaque blobs; they carry spatial structure (they're VAE latents, so they have a 2D grid). This node takes your MASK, resizes it to the reference latent's resolution, and multiplies the reference's latent values by a per-pixel scalar derived from the mask:

multiplier = 1 - strength * (1 - mask)

Where the mask is black (0), the multiplier is 1 - strength - the reference is attenuated there. Where the mask is white (1), the multiplier is 1 and the reference passes through untouched. With invert_mask on, that flips. The modified reference replaces reference_latents[reference_index] in your conditioning - the rest of the conditioning is untouched.

Two niceties make it usable rather than crude. feather (0–64) blurs the mask edges with a Gaussian so you don't get a hard latent seam, and strength (0–1) controls how completely the masked regions are suppressed - you can leave a ghost of the reference instead of erasing it.

The inputs that matter

• conditioning - the reference-bearing conditioning to modify (comes from a reference-attachment node).
• mask - your painted mask, from any mask-producing node (load an image's alpha, paint in the UI, or draw it with a mask editor).
• strength (default 1.0) - full suppression at 1.0, partial at lower values.
• invert_mask - flips which regions are kept.
• feather (default 0) - Gaussian edge softening in pixels.
• reference_index (0–7) - which attached reference to mask, when you have several.

Output is a single CONDITIONING, to be threaded forward into the KSampler (or into the reference controllers).

Where it sits in the workflow

On the conditioning path after the reference-attachment node and before the attention controllers and sampler. The README's example chain puts the conditioning-manipulation nodes between your CLIP encoder and the reference/attention nodes - this is one of those.

The classic use: a reference image of a person where you want the pose and style but the model keeps copying the background. Mask out the background of the reference (or invert and mask in just the subject) and the edit gets the part you care about without the part you don't.

Install

Same pack, same trivial install - no deps, no downloads:

cd ComfyUI/custom_nodes
git clone https://github.com/ChrisColeTech/ComfyUI-Flux-Reference-Tools

Restart, search "Flux Mask Ref Controller" under 🤖 CCTech/Flux Reference, or install via ComfyUI Manager.

Common issues

• Nothing is masked. If the conditioning has no reference latents at the index you chose, the node quietly skips that item and logs it in debug mode - check that a reference-attachment node ran first, and that reference_index matches the reference you meant.
• Hard edges in the output. Bump feather. A mask at latent resolution with zero feather gives a razor-sharp boundary that reads as an artifact.
• Mask orientation / resolution surprises. The mask gets resized (bilinear) to the latent grid, so a low-res or oddly-aspect-ratio mask still works - but a mask drawn at a different aspect ratio than the reference gets stretched. Keep them close.
• The reference leaks anyway. At strength < 1 you're deliberately leaving a fraction of it. If you want it gone, keep strength at 1.0 - a masked-out reference still contributes through the unmasked region.