Comfy-Org/ComfyUI · error · ValueError

JoyImage reference inputs must contain one image each

Error message

JoyImage reference inputs must contain one image each

What it means

Raised by _resize_reference() in the JoyImage (JoyCaption) reference pipeline: each reference image tensor passed to CLIP vision encoding must have batch dimension exactly 1, because the bucketing + resize path produces a single conditioning reference per image. Feeding a batched tensor (shape[0] > 1) raises immediately.

Source

Thrown at comfy_extras/nodes_joyimage.py:46

    (1664, 576),
    (1728, 576),
    (1792, 512), (1792, 576),
    (1856, 512),
    (1920, 512),
    (1984, 512),
    (2048, 512),
]
# fmt: on


def _find_best_bucket(height: int, width: int) -> tuple[int, int]:
    target_ratio = height / width
    return min(BUCKETS_1024, key=lambda hw: abs(hw[0] / hw[1] - target_ratio))


def _resize_reference(image):
    if image.shape[0] != 1:
        raise ValueError("JoyImage reference inputs must contain one image each")
    samples = image.movedim(-1, 1)
    bucket_h, bucket_w = _find_best_bucket(samples.shape[2], samples.shape[3])
    resized = comfy.utils.common_upscale(samples, bucket_w, bucket_h, "bilinear", "center")
    return resized.movedim(1, -1)[:, :, :, :3]


def _encode(clip, prompt, vae, images):
    resized_images = [_resize_reference(image) for image in images]
    conditioning = clip.encode_from_tokens_scheduled(clip.tokenize(prompt, images=resized_images))
    if vae is not None and resized_images:
        ref_latents = [vae.encode(image) for image in resized_images]
        conditioning = node_helpers.conditioning_set_values(
            conditioning, {"reference_latents": ref_latents}, append=True,
        )
    return conditioning


class TextEncodeJoyImageEdit(io.ComfyNode):

View on GitHub (pinned to 1c6d8d45b3)

Solutions

Slice the batch before the node: pass image[0:1] so shape[0] == 1.
Use a batch-split node (e.g. ImageFromBatch / RepeatImageBatch with count 1) upstream.
For multiple references, wire each single image into the node's separate reference inputs rather than one batched tensor.

Example fix

# before
refs = [image]           # image.shape == (8, H, W, 3) -> raises

# after
refs = [image[i:i+1] for i in range(image.shape[0])]  # or just image[:1]

Defensive patterns

Strategy: validation

Validate before calling

for name, image in zip(ref_names, images):
    assert image.shape[0] == 1, f"{name} has batch {image.shape[0]}; split it: image[i:i+1]"

Type guard

def is_single_reference(image) -> bool:
    return image.ndim == 4 and image.shape[0] == 1

Try / catch

try:
    cond = _encode(clip, prompt, vae, images)
except ValueError as e:
    if "one image each" in str(e):
        images = [im[0:1] for im in images]
        cond = _encode(clip, prompt, vae, images)
    else:
        raise

Prevention

Slice batches to length 1 before JoyImage reference inputs.
Use batch-split nodes instead of feeding frame batches.
Wire multiple single images into separate reference inputs.

When it happens

Trigger: Connecting a LoadImage batch or a video-frame batch (B>1) into the reference image input of the JoyImage encode node; upstream nodes that expand a single image into an animation batch.

Common situations: Batch workflows where every image input inherits a batch dimension; using image list nodes that concatenate frames into one tensor.

Related errors

AI-assisted analysis of Comfy-Org/ComfyUI@1c6d8d45b3 (2026-08-14). Data as JSON: /api/errors/9c95fac219931550. Report an issue: GitHub.