{"record":{"id":"5d8565ce939c7dc5","repo":"Comfy-Org/ComfyUI","slug":"at-least-one-reference-image-must-be-provided","errorCode":null,"errorMessage":"At least one reference image must be provided.","messagePattern":"At least one reference image must be provided\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_api_nodes/nodes_wan.py","lineNumber":2294,"sourceCode":"        model: dict,\n        seed: int,\n        watermark: bool,\n    ):\n        validate_string(model[\"prompt\"], strip_whitespace=False, min_length=1)\n        reference_images = model.get(\"reference_images\", {})\n        for key in reference_images:\n            validate_image_dimensions(reference_images[key], min_width=400, min_height=400)\n            validate_image_aspect_ratio(reference_images[key], (1, 2.5), (2.5, 1), strict=False)\n        media = []\n        for key in reference_images:\n            media.append(\n                Wan27MediaItem(\n                    type=\"reference_image\",\n                    url=await upload_image_to_comfyapi(cls, image=reference_images[key]),\n                )\n            )\n        if not media:\n            raise ValueError(\"At least one reference image must be provided.\")\n\n        initial_response = await sync_op(\n            cls,\n            ApiEndpoint(\n                path=\"/proxy/wan/api/v1/services/aigc/video-generation/video-synthesis\",\n                method=\"POST\",\n            ),\n            response_model=TaskCreationResponse,\n            data=Wan27ReferenceVideoTaskCreationRequest(\n                model=model[\"model\"],\n                input=Wan27ReferenceVideoInputField(\n                    prompt=model[\"prompt\"],\n                    negative_prompt=None,\n                    media=media,\n                ),\n                parameters=Wan27ReferenceVideoParametersField(\n                    resolution=model[\"resolution\"],\n                    ratio=model[\"ratio\"],","sourceCodeStart":2276,"sourceCodeEnd":2312,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_api_nodes/nodes_wan.py#L2276-L2312","documentation":"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.","triggerScenarios":"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.","commonSituations":"Reference image batch input left at zero entries; workflow saved with the reference input disconnected; assuming reference videos are accepted here (they are not).","solutions":["Connect at least one reference image to the node","Ensure the reference image batch actually contains entries before executing","Use the Wan2ReferenceVideoApi node if video references are needed"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"reference_images = model.get(\"reference_images\", {})\nif not reference_images:\n    raise ValueError(\"connect at least one reference image\")\nfor img in reference_images.values():\n    validate_image_dimensions(img, min_width=400, min_height=400)\n    validate_image_aspect_ratio(img, (1, 2.5), (2.5, 1), strict=False)","typeGuard":"def has_reference_images(m: dict) -> bool:\n    return bool(m.get(\"reference_images\"))","tryCatchPattern":null,"preventionTips":["This node takes images only — use Wan2ReferenceVideoApi for video references","Check the reference batch is non-empty before running"],"tags":["happy-horse","wan","api-node","validation","reference-image"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}