{"record":{"id":"cff1517eca4676a0","repo":"calesthio/OpenMontage","slug":"image-to-video-requires-reference-image-path-or-re","errorCode":null,"errorMessage":"image_to_video requires reference_image_path or reference_image_url","messagePattern":"image_to_video requires reference_image_path or reference_image_url","errorType":"exception","errorClass":"ComfyUIError","httpStatus":null,"severity":"error","filePath":"tools/video/comfyui_video.py","lineNumber":635,"sourceCode":"    ) -> tuple[dict, str]:\n        width = inputs.get(\"width\", 640)\n        height = inputs.get(\"height\", 640)\n        num_frames = inputs.get(\"num_frames\", 81)\n\n        # Resolve reference image\n        ref_path = inputs.get(\"reference_image_path\")\n        ref_url = inputs.get(\"reference_image_url\")\n\n        if ref_url and not ref_path:\n            # Download to a temp location\n            resp = requests.get(ref_url, timeout=60)\n            resp.raise_for_status()\n            ref_path = str(output_path.with_suffix(\".ref.png\"))\n            Path(ref_path).parent.mkdir(parents=True, exist_ok=True)\n            Path(ref_path).write_bytes(resp.content)\n\n        if not ref_path:\n            raise ComfyUIError(\n                \"image_to_video requires reference_image_path or reference_image_url\"\n            )\n\n        # Upload to ComfyUI\n        upload_name = f\"om_{output_path.stem}.png\"\n        server_name = self._client.upload_image(Path(ref_path), upload_name)\n\n        workflow = ComfyUIClient.load_workflow(_WORKFLOWS / \"wan22-i2v-4step.json\")\n        workflow = ComfyUIClient.patch_workflow(\n            workflow,\n            {\n                \"93\": {\"text\": inputs[\"prompt\"]},\n                \"97\": {\"image\": server_name},\n                \"98\": {\"width\": width, \"height\": height, \"length\": num_frames},\n                \"86\": {\"noise_seed\": seed},\n                \"108\": {\"filename_prefix\": output_path.stem},\n            },\n        )","sourceCodeStart":617,"sourceCodeEnd":653,"githubUrl":"https://github.com/calesthio/OpenMontage/blob/95e1c3d0ab93482159818560f6a8c8e866b9139f/tools/video/comfyui_video.py#L617-L653","documentation":"Raised as ComfyUIError by the image_to_video branch of ComfyUIVideoTool when neither reference_image_path nor reference_image_url is set. If a URL is given it is downloaded to a temp .ref.png first; the error means both keys were absent so there is no conditioning frame to upload.","triggerScenarios":"Calling the comfyui i2v workflow with prompt only; passing the image under 'image_path' or 'image' (unread keys); ref_url present but falsy (empty string) so the download branch is skipped and ref_path stays unset.","commonSituations":"Reusing atlas_video input keys against the comfyui tool (different key names); a URL variable that is None after an optional upload step; agent tool call missing the image argument.","solutions":["Pass reference_image_path (local file) or reference_image_url (remote URL, auto-downloaded with a 60s timeout)","Check the exact key names — this tool reads reference_image_path/reference_image_url, not image_path/image_url","For large remote images, pre-download yourself so you control timeouts and retries"],"exampleFix":"# before\ninputs = {'prompt':'a waving flag','operation':'image_to_video'}\n\n# after\ninputs = {'prompt':'a waving flag','operation':'image_to_video','reference_image_path':'assets/flag.png'}","handlingStrategy":"validation","validationCode":"ref = inputs.get('reference_image_path') or inputs.get('reference_image_url')\nif not ref:\n    raise ValueError('i2v needs reference_image_path or reference_image_url')\nif inputs.get('reference_image_path'):\n    p = Path(inputs['reference_image_path'])\n    if not p.is_file():\n        raise ValueError(f'reference image missing: {p}')","typeGuard":"def has_i2v_reference(inputs: dict) -> bool:\n    return bool(inputs.get('reference_image_path') or inputs.get('reference_image_url'))","tryCatchPattern":"try:\n    result = comfyui_video.run(inputs=inputs)\nexcept ComfyUIError as e:\n    if 'reference_image' in str(e):\n        raise SystemExit('attach a reference image for image_to_video') from e\n    raise","preventionTips":["Use this tool's exact keys (reference_image_path/url), not atlas_video's","Verify local image files exist before the call","Pre-download remote images yourself to control timeouts"],"tags":["comfyui","image-to-video","validation"],"backgroundTag":null,"analyzedSha":"95e1c3d0ab93482159818560f6a8c8e866b9139f","analyzedAt":"2026-08-15T06:31:20.014Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}