calesthio/OpenMontage · error · ComfyUIError

image_to_video requires reference_image_path or reference_im

Error message

image_to_video requires reference_image_path or reference_image_url

What it means

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.

Source

Thrown at tools/video/comfyui_video.py:635

    ) -> tuple[dict, str]:
        width = inputs.get("width", 640)
        height = inputs.get("height", 640)
        num_frames = inputs.get("num_frames", 81)

        # Resolve reference image
        ref_path = inputs.get("reference_image_path")
        ref_url = inputs.get("reference_image_url")

        if ref_url and not ref_path:
            # Download to a temp location
            resp = requests.get(ref_url, timeout=60)
            resp.raise_for_status()
            ref_path = str(output_path.with_suffix(".ref.png"))
            Path(ref_path).parent.mkdir(parents=True, exist_ok=True)
            Path(ref_path).write_bytes(resp.content)

        if not ref_path:
            raise ComfyUIError(
                "image_to_video requires reference_image_path or reference_image_url"
            )

        # Upload to ComfyUI
        upload_name = f"om_{output_path.stem}.png"
        server_name = self._client.upload_image(Path(ref_path), upload_name)

        workflow = ComfyUIClient.load_workflow(_WORKFLOWS / "wan22-i2v-4step.json")
        workflow = ComfyUIClient.patch_workflow(
            workflow,
            {
                "93": {"text": inputs["prompt"]},
                "97": {"image": server_name},
                "98": {"width": width, "height": height, "length": num_frames},
                "86": {"noise_seed": seed},
                "108": {"filename_prefix": output_path.stem},
            },
        )

View on GitHub (pinned to 95e1c3d0ab)

Solutions

1. Pass reference_image_path (local file) or reference_image_url (remote URL, auto-downloaded with a 60s timeout)
2. Check the exact key names — this tool reads reference_image_path/reference_image_url, not image_path/image_url
3. For large remote images, pre-download yourself so you control timeouts and retries

Example fix

# before
inputs = {'prompt':'a waving flag','operation':'image_to_video'}

# after
inputs = {'prompt':'a waving flag','operation':'image_to_video','reference_image_path':'assets/flag.png'}

ref = inputs.get('reference_image_path') or inputs.get('reference_image_url')
if not ref:
    raise ValueError('i2v needs reference_image_path or reference_image_url')
if inputs.get('reference_image_path'):
    p = Path(inputs['reference_image_path'])
    if not p.is_file():
        raise ValueError(f'reference image missing: {p}')

def has_i2v_reference(inputs: dict) -> bool:
    return bool(inputs.get('reference_image_path') or inputs.get('reference_image_url'))

try:
    result = comfyui_video.run(inputs=inputs)
except ComfyUIError as e:
    if 'reference_image' in str(e):
        raise SystemExit('attach a reference image for image_to_video') from e
    raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• image_to_video requires image_url, image_path, or reference_
• image_to_video requires image_url or image_path
• image_to_video requires exactly one reference image
• provide only one of end_image_url/end_image_path
• ${res.status} ${url}

AI-assisted analysis of calesthio/OpenMontage@95e1c3d0ab (2026-08-15). Data as JSON: /api/errors/cff1517eca4676a0. Report an issue: GitHub.