{"record":{"id":"9059acd1f3d63df6","repo":"Comfy-Org/ComfyUI","slug":"at-least-one-reference-video-or-reference-image-mu","errorCode":null,"errorMessage":"At least one reference video or reference image must be provided.","messagePattern":"At least one reference video or reference image must be provided\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"comfy_api_nodes/nodes_wan.py","lineNumber":1610,"sourceCode":"        watermark: bool,\n    ):\n        validate_string(model[\"prompt\"], strip_whitespace=False, min_length=1)\n        media = []\n        reference_videos = model.get(\"reference_videos\", {})\n        for key in reference_videos:\n            media.append(\n                Wan27MediaItem(type=\"reference_video\", url=await upload_video_to_comfyapi(cls, reference_videos[key]))\n            )\n        reference_images = model.get(\"reference_images\", {})\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 video or reference image must be provided.\")\n        if len(media) > 5:\n            raise ValueError(\n                f\"Too many references ({len(media)}). The maximum total of reference videos and images is 5.\"\n            )\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=model[\"negative_prompt\"] or None,\n                    media=media,","sourceCodeStart":1592,"sourceCodeEnd":1628,"githubUrl":"https://github.com/Comfy-Org/ComfyUI/blob/1c6d8d45b3693bfbb32385b410d813a7fd6be216/comfy_api_nodes/nodes_wan.py#L1592-L1628","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Connect at least one reference video or reference image to the node's reference inputs","If using the model dict directly, ensure reference_videos or reference_images has at least one entry","Validate before running: cheap client-side check beats uploading nothing and failing after uploads"],"exampleFix":"// before\nmodel={\"model\": \"wan2.5-i2v-preview\", \"reference_videos\": {}, \"reference_images\": {}}\n// after\nmodel={\"model\": \"wan2.5-i2v-preview\", \"reference_videos\": {\"0\": my_ref_video}}","handlingStrategy":"validation","validationCode":"reference_videos = model.get(\"reference_videos\", {})\nreference_images = model.get(\"reference_images\", {})\nif not (reference_videos or reference_images):\n    raise ValueError(\"connect at least one reference video or image\")","typeGuard":"def has_references(m: dict) -> bool:\n    return bool(m.get(\"reference_videos\")) or bool(m.get(\"reference_images\"))","tryCatchPattern":null,"preventionTips":["Check reference maps before starting the (long) graph run","Wire reference inputs explicitly rather than relying on defaults"],"tags":["wan","api-node","validation","reference-video"],"backgroundTag":null,"analyzedSha":"1c6d8d45b3693bfbb32385b410d813a7fd6be216","analyzedAt":"2026-08-14T19:37:18.893Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}