Comfy-Org/ComfyUI · error · ValueError

At least one reference video or reference image must be prov

Error message

At least one reference video or reference image must be provided.

What it means

Raised by Wan2ReferenceVideoApi.execute when, after collecting uploads, the `media` list is empty — the model dict contained neither reference_videos nor reference_images. The Wan 2.7 reference-video endpoint requires at least one reference asset, so the node fails before task creation.

Source

Thrown at comfy_api_nodes/nodes_wan.py:1610

        watermark: bool,
    ):
        validate_string(model["prompt"], strip_whitespace=False, min_length=1)
        media = []
        reference_videos = model.get("reference_videos", {})
        for key in reference_videos:
            media.append(
                Wan27MediaItem(type="reference_video", url=await upload_video_to_comfyapi(cls, reference_videos[key]))
            )
        reference_images = model.get("reference_images", {})
        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 video or reference image must be provided.")
        if len(media) > 5:
            raise ValueError(
                f"Too many references ({len(media)}). The maximum total of reference videos and images is 5."
            )

        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=model["negative_prompt"] or None,
                    media=media,

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Connect at least one reference video or reference image to the node's reference inputs
2. If using the model dict directly, ensure reference_videos or reference_images has at least one entry
3. Validate before running: cheap client-side check beats uploading nothing and failing after uploads

Example fix

// before
model={"model": "wan2.5-i2v-preview", "reference_videos": {}, "reference_images": {}}
// after
model={"model": "wan2.5-i2v-preview", "reference_videos": {"0": my_ref_video}}

reference_videos = model.get("reference_videos", {})
reference_images = model.get("reference_images", {})
if not (reference_videos or reference_images):
    raise ValueError("connect at least one reference video or image")

def has_references(m: dict) -> bool:
    return bool(m.get("reference_videos")) or bool(m.get("reference_images"))

When it happens

Trigger: The Wan2 model dict passed to the node has empty `reference_videos` and `reference_images` maps (or they are absent, since `.get(..., {})` defaults to empty). Any batch-size zero or unconnected reference inputs produce the same state.

Common situations: Using a batch/autogrow input for references with zero entries; wiring the model dict from a picker where reference inputs were left empty; workflow saved with references disconnected.

Related errors

• Too many references ({len(media)}). The maximum total of ref
• At least one reference image must be provided.
• Exactly one input image is required.
• MiniMax H3 reference videos need at least 5 frames (~0.2s at
• pose_start_percent ({}) must not be greater than pose_end_pe

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