calesthio/OpenMontage · error · FileNotFoundError

Reference image not found: {ref}

Error message

Reference image not found: {ref}

What it means

FileNotFoundError from the Hunyuan image tool's reference-image resolver. Each reference is either passed through untouched (data: URI or http(s) URL) or treated as a local file; if it is not an existing regular file, resolution fails before any request is sent.

Source

Thrown at tools/graphics/hunyuan_image.py:396

        Each entry may be:
        - An HTTP(S) URL → passed through unchanged
        - A data URI (``data:...``) → passed through unchanged
        - A local file path → base64-encoded as a data URI

        Per upstream docs: single image 50-5000px per side, base64 < 6MB.
        Formats: jpg/jpeg/png/bmp/tiff/webp.
        """
        import base64

        resolved: list[str] = []
        for ref in refs:
            if ref.startswith("data:") or ref.startswith("http://") or ref.startswith("https://"):
                resolved.append(ref)
                continue

            image_path = Path(ref)
            if not image_path.is_file():
                raise FileNotFoundError(f"Reference image not found: {ref}")

            raw = image_path.read_bytes()
            max_raw = 6 * 1024 * 1024  # 6MB per upstream limit
            if len(raw) > max_raw:
                raise ValueError(
                    f"Image too large ({len(raw)} bytes). Max ~6MB raw."
                )

            suffix = image_path.suffix.lower()
            mime_map = {
                ".jpg": "image/jpeg",
                ".jpeg": "image/jpeg",
                ".png": "image/png",
                ".bmp": "image/bmp",
                ".tiff": "image/tiff",
                ".tif": "image/tiff",
                ".webp": "image/webp",
            }

View on GitHub (pinned to 95e1c3d0ab)

Solutions

1. Pre-check every reference with Path(ref).expanduser().resolve().is_file() before calling the tool
2. Use absolute paths for all local references
3. Prefix remote references with https:// so they take the URL pass-through branch
4. Verify upstream pipeline steps actually wrote the referenced files

Example fix

// before
refs = ["~/refs/style.png"]
// after
from pathlib import Path
refs = [str(Path(r).expanduser().resolve()) for r in ["~/refs/style.png"]]
for r in refs:
    if not r.startswith(("data:", "http://", "https://")):
        assert Path(r).is_file(), f"reference missing: {r}"

from pathlib import Path

resolved = []
for ref in refs:
    if ref.startswith(("data:", "http://", "https://")):
        resolved.append(ref)
    else:
        p = Path(ref).expanduser().resolve()
        assert p.is_file(), f"reference missing: {ref}"
        resolved.append(str(p))

try:
        result = hunyuan_tool.run(inputs)
    except FileNotFoundError as e:
        # a reference path does not exist; check spelling/cwd

When it happens

Trigger: Passing a reference string that is not a data:/http(s) prefix and does not exist on disk: typo, wrong cwd for a relative path, '~' not expanded (the code uses Path(ref) and is_file() directly), or a file produced by an earlier step that has not been written yet.

Common situations: Agent chains tools and forwards a path from a previous step that failed silently; relative references resolved from a different working directory; Windows-style paths on Linux runners.

Related errors

• Image not found: {path}
• Image not found: {image_path}
• {label} not found: {media_path}
• Local reference image not found: {path}
• Input file not found: {path}

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