Comfy-Org/ComfyUI · error · ValueError

At least one reference image must be provided.

Error message

At least one reference image must be provided.

What it means

Raised by HappyHorseReferenceVideoApi.execute when the `media` list built from the model dict's reference_images is empty. Unlike the Wan2 variant, this node only accepts reference images (no videos), each already validated for min 400x400 dimensions and 1:2.5–2.5:1 aspect ratio; with zero images it fails before task creation.

Source

Thrown at comfy_api_nodes/nodes_wan.py:2294

        model: dict,
        seed: int,
        watermark: bool,
    ):
        validate_string(model["prompt"], strip_whitespace=False, min_length=1)
        reference_images = model.get("reference_images", {})
        for key in reference_images:
            validate_image_dimensions(reference_images[key], min_width=400, min_height=400)
            validate_image_aspect_ratio(reference_images[key], (1, 2.5), (2.5, 1), strict=False)
        media = []
        for key in reference_images:
            media.append(
                Wan27MediaItem(
                    type="reference_image",
                    url=await upload_image_to_comfyapi(cls, image=reference_images[key]),
                )
            )
        if not media:
            raise ValueError("At least one reference image must be provided.")

        initial_response = await sync_op(
            cls,
            ApiEndpoint(
                path="/proxy/wan/api/v1/services/aigc/video-generation/video-synthesis",
                method="POST",
            ),
            response_model=TaskCreationResponse,
            data=Wan27ReferenceVideoTaskCreationRequest(
                model=model["model"],
                input=Wan27ReferenceVideoInputField(
                    prompt=model["prompt"],
                    negative_prompt=None,
                    media=media,
                ),
                parameters=Wan27ReferenceVideoParametersField(
                    resolution=model["resolution"],
                    ratio=model["ratio"],

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Connect at least one reference image to the node
2. Ensure the reference image batch actually contains entries before executing
3. Use the Wan2ReferenceVideoApi node if video references are needed

reference_images = model.get("reference_images", {})
if not reference_images:
    raise ValueError("connect at least one reference image")
for img in reference_images.values():
    validate_image_dimensions(img, min_width=400, min_height=400)
    validate_image_aspect_ratio(img, (1, 2.5), (2.5, 1), strict=False)

def has_reference_images(m: dict) -> bool:
    return bool(m.get("reference_images"))

When it happens

Trigger: reference_images in the model dict is empty or missing (`.get` default is empty). This is checked after the dimension/aspect validation loop, so it triggers when no images exist at all.

Common situations: Reference image batch input left at zero entries; workflow saved with the reference input disconnected; assuming reference videos are accepted here (they are not).

Related errors

• At least one reference video or reference image must be prov
• Too many references ({len(media)}). The maximum total of ref
• Exactly one input image is required.
• pose_start_percent ({}) must not be greater than pose_end_pe
• Not enough previous frames provided.

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