Qwen 2.1 UNION Image Reference Encode:
QwenImage21UnionReferenceEncode prepares reference-guided image editing for Qwen Image 2.1 workflows, combining written instructions with visual context so you can describe changes while referring to an existing image and additional visual examples. Available in ComfyUI as “Qwen 2.1 UNION Image Reference Encode” under “Qwen Image 2.1/Union,” it treats the primary picture as the editing target and canvas, while additional pictures serve as references. It uses ComfyUI’s native Qwen Image 2.1 encoding implementation rather than implementing a separate encoding method, keeping preparation aligned with that implementation. Its main benefit is coordinating the text, image references, and editing canvas in one preparation step. It supports workflows that also use UNION control or masked editing, but it does not itself apply control maps, configure masks, or generate the finished image.
Qwen 2.1 UNION Image Reference Encode Input Parameters:
clip
Required; type: CLIP. Supplies the text-encoding component used by the native Qwen Image 2.1 encoder to turn your written instructions into information the image model can process. Connect a CLIP component compatible with your Qwen Image 2.1 workflow; the socket’s name does not mean an arbitrary CLIP encoder will work. An incompatible encoder can prevent encoding or produce errors downstream. This wrapper forwards the component directly to the native encoder without performing its own compatibility checks. No default value, numeric range, or selectable options are defined.
vae
Required; type: VAE. Supplies the image-to-latent encoding component used during native reference preparation. A latent is a compact representation used by the image-generation model rather than a directly viewable picture. Use a VAE compatible with your Qwen Image 2.1 model so image preparation and later sampling operate in the expected representation. The node forwards this component to the native encoder without adding conversion or compatibility logic. No default value, numeric range, or selectable options are defined.
reference_image
Required; type: IMAGE. Provides the primary image, which is forwarded as image_1 and serves as the editing target and canvas. This is the picture you want to modify, rather than merely an example of a desired appearance. It must contain exactly one image: a batch containing two or more images is rejected before encoding. The node’s description specifically requires you to use the latent produced by this node so the sampling canvas matches this primary image. No default image, fixed width, fixed height, or numeric range is defined in this wrapper.
prompt
Required; type: STRING; default: an empty string. Provides your positive editing instructions to the native encoder. Describe what you want to change, what should remain, and how any additional reference pictures should be used. For example, Edit <image1> using the color palette of <image2>, keeping the original composition makes the intended relationship explicit; the supplied test demonstrates forwarding prompts containing these image-reference markers, although it does not establish any guarantee about the resulting edit. This is a multiline text field, and the wrapper forwards its contents unchanged without validating the wording. No length limit or predefined options are specified.
negative_prompt
Required; type: STRING; default: an empty string. Provides negative text guidance to the native Qwen Image 2.1 encoder, allowing you to describe unwanted characteristics such as text overlays or particular visual artifacts. Its practical effect depends on the native encoder, model, and sampling configuration; this wrapper does not enforce exclusions or independently adjust their strength. You can leave it empty when you do not need additional negative instructions. This is a multiline text field with no specified length limit or predefined options.
resolution
Required; type: INT; default: 1024; minimum: 0; maximum: 4096; step: 32. Passes the requested resolution setting to the native Qwen Image 2.1 encoder, where the image and latent preparation behavior is determined. This wrapper does not calculate dimensions itself, and the supplied code does not establish whether this value represents a particular side length, a resolution target, or another sizing convention in the native implementation. Consequently, do not assume that 1024 necessarily produces a square 1024-by-1024 canvas. Start with the default unless your workflow requires another setting, and check the resulting dimensions when matching other workflow components. Although 0 is accepted by the interface, its special meaning, if any, is not defined in the supplied implementation.
reference_image_2
Optional; type: IMAGE. Supplies a second picture as visual reference material, forwarded under the fixed name image_2. Unlike the primary reference, it is not designated as the editing canvas. Use your prompt to explain its intended role, such as providing a palette or an example of an appearance, rather than expecting the node to infer the relationship automatically. When connected, it must contain exactly one image or encoding stops with a validation error. When omitted, it is not included in the image collection sent to the native encoder. No default image, fixed dimensions, or numeric range is defined.
reference_image_3
Optional; type: IMAGE. Supplies a third picture as additional visual reference material, forwarded under the fixed name image_3. It lets you provide another visual example while retaining the primary image as the editing target. Explain its purpose in your prompt to distinguish it from the other references. When connected, it must contain exactly one image. The numbering is tied to the socket: if you connect this input without connecting reference_image_2, it is still forwarded as image_3, not renamed to image_2; whether that arrangement is supported downstream depends on the native encoder. No default image, fixed dimensions, or numeric range is defined.
Qwen 2.1 UNION Image Reference Encode Output Parameters:
positive
Type: CONDITIONING. Contains the positive conditioning returned by the native Qwen Image 2.1 encoder after processing the supplied instructions and references. Conditioning is model-readable guidance, not a rendered picture or a plain-text copy of the prompt. Connect it to the sampler’s positive-conditioning path, or through any conditioning-processing nodes required by your workflow before sampling. This wrapper returns the native result unchanged and does not expose its internal contents or add an independent guidance-strength setting.
negative
Type: CONDITIONING. Contains the negative conditioning returned by the native encoder. It provides the sampler with the negative-guidance counterpart to positive and should be connected to the corresponding negative-conditioning path. Even when your negative prompt is empty, use the returned output rather than assuming it is unnecessary, because its exact contents and preparation are managed by the native implementation. This output is not a guarantee that every unwanted feature will be excluded.
latent
Type: LATENT. Contains the latent returned alongside the conditioning by the native Qwen Image 2.1 encoder. It supplies the sampling canvas associated with the primary reference image. The node’s description explicitly states that the sampler must use this node’s latent to match image_1; substituting an unrelated empty latent or one prepared from another picture can break that alignment. Connect it to the sampler’s latent-image input. It is an internal representation, not a viewable image; the sampled result normally needs VAE decoding before you can preview or save it.
Qwen 2.1 UNION Image Reference Encode Usage Tips:
-
Start with only
reference_imageconnected andresolutionset to 1024. Confirm that the basic edit works before adding extra references or UNION control, making it easier to identify which part of the workflow needs adjustment. -
Write instructions that distinguish the editing target from visual examples. For instance, use
Keep the composition of <image1> and use the color palette of <image2>rather than an ambiguous instruction such as “combine these.” -
Connect
positive,negative, andlatentfrom the same execution to the sampling workflow. In particular, do not replace this node’s latent with a separately created canvas when editing the primary reference. -
Supply one image per image socket. If an upstream node produces a batch, select a single image before connecting it; use the optional reference sockets for separate reference pictures instead of packing them into one batch.
-
Add references in order: first the primary image, then
reference_image_2, thenreference_image_3. This keeps prompt references easy to follow and avoids relying on undocumented downstream handling of a missing second image. -
For UNION control, use a prepared control map in the separate UNION
control_imageconnection. Additional reference pictures provide visual context and should not be assumed to replace the control map. -
For masked editing in the surrounding UNION workflow, also connect the source picture to
inpaint_imageas instructed by this node’s description. This node has no mask input and does not configure masked editing by itself. -
Keep the encoder, VAE, model, and sampling configuration compatible with Qwen Image 2.1. If memory becomes a problem at higher resolution settings, try a lower nonzero setting and fewer optional references, then check whether the resulting detail meets your needs.
Qwen 2.1 UNION Image Reference Encode Common Errors and Solutions:
reference_image must contain one image.
- Explanation: The primary image input has a batch size other than one. This exact message is raised by the node before calling the native encoder.
- Solution: Select one picture from the incoming batch or load a single picture, then reconnect it to
reference_image. To edit multiple pictures, process them separately.
reference_image_2 must contain one image.
- Explanation: The second reference input contains a batch rather than exactly one picture. Optional references are subject to the same single-image check as the primary image.
- Solution: Extract the single reference you want to use, or disconnect this optional input if it is unnecessary.
reference_image_3 must contain one image.
- Explanation: The third reference input has a batch size other than one. The validation loop checks this socket independently.
- Solution: Connect exactly one picture to
reference_image_3. Do not combine multiple reference pictures into a batch for this socket.
No module named 'comfy_extras.nodes_qwen'
- Explanation: This is a possible Python import error, not a custom error defined by the node. The node imports ComfyUI’s Qwen implementation at execution time, so execution cannot continue if that module is unavailable.
- Solution: Update ComfyUI to a version that includes the required Qwen nodes, confirm the custom node is installed in the same ComfyUI installation you are launching, and restart ComfyUI.
cannot import name 'TextEncodeQwenImage21' from 'comfy_extras.nodes_qwen'
- Explanation: This is a possible dependency-version error. The Qwen module may exist while the required
TextEncodeQwenImage21class is missing, for example when the installed ComfyUI version does not provide it. - Solution: Install a compatible ComfyUI version that includes
TextEncodeQwenImage21, update the custom node as needed, and restart. The presence of other Qwen encoding classes alone does not satisfy this dependency.
Downstream encoding or sampling fails with a compatibility or dimension error
- Explanation: The exact message depends on the failing component and is not specified in the supplied code. Possible causes include incompatible encoder or VAE components, or a sampling canvas that does not match the primary reference. This wrapper validates image batch sizes but does not check those other conditions.
- Solution: Confirm that your model, CLIP component, and VAE belong to a compatible Qwen Image 2.1 workflow. Use this node’s
latentoutput for sampling, and first test with one primary reference and the default resolution before restoring additional components.
Out of memory during encoding or sampling
- Explanation: This is a possible runtime resource error, not a message explicitly raised by this wrapper. Image-reference processing and sampling require memory, and higher resolution settings or additional references can increase resource demands.
- Solution: Try a lower nonzero
resolution, remove optional references temporarily, and close other GPU-intensive applications. Retry the simplest working configuration before increasing its demands.
The wrong picture is edited or the canvas does not match
- Explanation: This is a workflow symptom rather than a defined exception. The primary reference determines the edit target and canvas; optional references do not replace it, and using a separately prepared latent can disrupt the intended alignment.
- Solution: Put the picture you want to edit in
reference_image, place visual examples in the optional sockets, clarify their roles in the prompt, and connect this node’slatentoutput to the sampler.
