DOGMA OptionalReferenceImage v2

The annoyance it removes

Core Load Image does not have an "empty" option. So if your graph can take a style reference but doesn't always need one, you have three bad choices: point it at some placeholder file that then silently influences your render, keep two versions of the workflow, or bypass the loader and watch half the graph go dark.

DOGMAOptionalReferenceImageV2 is the fourth option: a dropdown that lists your input/ images with (none) at the top, and returns nothing when you pick it.

How it works

It's a thin wrapper around ComfyUI's own loader - the file list comes from Load Image's own input definition, with (none) prepended, and the node keeps the upload button so you can drop a file straight onto the widget. VALIDATE_INPUTS and IS_CHANGED both delegate to the core loader, so caching and file-change detection behave exactly like Load Image.

The one behavioural difference is in load(): if the selection is (none), it returns (None,) instead of a tensor.

That's the null-output placeholder idiom from the plumbing side of ComfyUI. An optional input downstream that isn't connected reads None - that's how the engine represents "nothing here" - and a node deliberately emitting None is how you mute a branch from inside the data rather than by bypassing nodes on the canvas. Intentional, documented, and much easier to reason about than a graph half-bypassed by hand.

Inputs and outputs

• image - one enum input containing (none) plus every image file in your ComfyUI input folder, with upload enabled. Defaults to (none), which is the whole point.

Output:

• IMAGE - a single image tensor, or None. Note the socket is literally named IMAGE, so if you're matching wires by name, that's what to look for.

Wiring it up

The intended consumer in this pack is the Qwen reference encoder, which takes the reference as an optional input and only uses it when a use_reference boolean is also on:

DOGMAOptionalReferenceImageV2 ──► reference_image (optional) ──► Qwen encode node
                                              ▲
                                   use_reference (boolean)

The encoder checks both - reference present and the toggle on - so (none) plus use_reference = true degrades to a plain single-image encode rather than an error. That double gate is the pattern worth copying if you're writing this yourself: a None arriving where a tensor is expected is fine only if every consumer is written to expect it.

And that's the trap. The failure moves downstream. If you wire this node's output into anything that declares a required IMAGE input, you get a type error at the consumer, not here - and the error will name the consumer node, which sends people looking in the wrong place. Rule of thumb: this node only pairs with inputs marked optional.

One more, minor but real: the file list is read when the node definition is built, so an image you copy into input/ while ComfyUI is running may not appear in the dropdown until you refresh the node definitions. Same behaviour as core Load Image, so it should feel familiar rather than surprising.

Why it's here at all

The workflow this came from is a restoration pipeline with a Qwen Image Edit pass near the front - the class of tool the upscaling doc calls the incumbent since late 2025, where a reference or a LoRA steers the edit rather than a ControlNet stack. In that shape, "do I have a style reference for this shot?" is a per-scene question, and a scene set where some frames have references and some don't is completely normal. Hard-coding a loader means either a fake reference on the frames that don't have one, or a second workflow you have to keep in sync. Neither is good.

Install

Manager → search DOGMA Nodes (publisher axior), or:

cd ComfyUI/custom_nodes
git clone https://github.com/axior/ComfyUI-DOGMA-Nodes
# restart ComfyUI

requirements.txt declares scipy>=1.10 as the pack's only Python dependency, and nothing is downloaded to models/. This particular node imports nothing beyond ComfyUI's own LoadImage, so its risk surface is essentially zero - it's one convenience wrapper over a core node, and the only thing to remember is the None handling downstream.

Worth saying plainly since it's the pack's usual caveat and it doesn't bite here: DOGMA Nodes is one author's pipeline published as nodes, CPU-validated with mocked model calls, with no real community footprint. For a loader wrapper that just adds (none) to a dropdown, that's fine. You can read the whole implementation in a minute.