Comfy-Org/ComfyUI · error · ValueError

Too many references ({len(media)}). The maximum total of ref

Error message

Too many references ({len(media)}). The maximum total of reference videos and images is 5.

What it means

Raised by Wan2ReferenceVideoApi.execute when the combined count of reference videos and images exceeds 5. The node counts entries appended to `media` from both the reference_videos and reference_images maps, then enforces the Wan 2.7 API limit of 5 total reference assets.

Source

Thrown at comfy_api_nodes/nodes_wan.py:1612

        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,
                ),
                parameters=Wan27ReferenceVideoParametersField(

View on GitHub (pinned to 1c6d8d45b3)

Solutions

1. Reduce total references (videos + images) to 5 or fewer
2. Pick the highest-quality references rather than uploading many and failing
3. Prefer trimming the list before the node runs so uploads are not wasted (the check currently happens after upload)

Example fix

// before
refs = {**videos, **images}  # 7 entries -> ValueError after upload
// after
refs = dict(list({**videos, **images}.items())[:5])

total = len(reference_videos) + len(reference_images)
if total > 5:
    reference_videos = dict(list(reference_videos.items())[: max(0, 5 - len(reference_images))])
    # or simply reject:
    # raise ValueError(f"{total} references exceeds the limit of 5")

def within_reference_limit(videos: dict, images: dict) -> bool:
    return len(videos) + len(images) <= 5

When it happens

Trigger: reference_videos plus reference_images entries total 6 or more in the model dict; e.g. 3 videos and 3 images. The check runs after uploads, so the failure surfaces late.

Common situations: Autogrow/batch reference inputs expanded past the limit; merging multiple reference workflows together; assuming the limit was per-type rather than total.

Related errors

• At least one reference video or reference image must be prov
• 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/0b2d4dd0a0a9077e. Report an issue: GitHub.