{"record":{"id":"fde98a0fd6043b31","repo":"calesthio/OpenMontage","slug":"reference-image-not-found-ref","errorCode":null,"errorMessage":"Reference image not found: {ref}","messagePattern":"Reference image not found: (.+?)","errorType":"exception","errorClass":"FileNotFoundError","httpStatus":null,"severity":"error","filePath":"tools/graphics/hunyuan_image.py","lineNumber":396,"sourceCode":"        Each entry may be:\n        - An HTTP(S) URL → passed through unchanged\n        - A data URI (``data:...``) → passed through unchanged\n        - A local file path → base64-encoded as a data URI\n\n        Per upstream docs: single image 50-5000px per side, base64 < 6MB.\n        Formats: jpg/jpeg/png/bmp/tiff/webp.\n        \"\"\"\n        import base64\n\n        resolved: list[str] = []\n        for ref in refs:\n            if ref.startswith(\"data:\") or ref.startswith(\"http://\") or ref.startswith(\"https://\"):\n                resolved.append(ref)\n                continue\n\n            image_path = Path(ref)\n            if not image_path.is_file():\n                raise FileNotFoundError(f\"Reference image not found: {ref}\")\n\n            raw = image_path.read_bytes()\n            max_raw = 6 * 1024 * 1024  # 6MB per upstream limit\n            if len(raw) > max_raw:\n                raise ValueError(\n                    f\"Image too large ({len(raw)} bytes). Max ~6MB raw.\"\n                )\n\n            suffix = image_path.suffix.lower()\n            mime_map = {\n                \".jpg\": \"image/jpeg\",\n                \".jpeg\": \"image/jpeg\",\n                \".png\": \"image/png\",\n                \".bmp\": \"image/bmp\",\n                \".tiff\": \"image/tiff\",\n                \".tif\": \"image/tiff\",\n                \".webp\": \"image/webp\",\n            }","sourceCodeStart":378,"sourceCodeEnd":414,"githubUrl":"https://github.com/calesthio/OpenMontage/blob/95e1c3d0ab93482159818560f6a8c8e866b9139f/tools/graphics/hunyuan_image.py#L378-L414","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pre-check every reference with Path(ref).expanduser().resolve().is_file() before calling the tool","Use absolute paths for all local references","Prefix remote references with https:// so they take the URL pass-through branch","Verify upstream pipeline steps actually wrote the referenced files"],"exampleFix":"// before\nrefs = [\"~/refs/style.png\"]\n// after\nfrom pathlib import Path\nrefs = [str(Path(r).expanduser().resolve()) for r in [\"~/refs/style.png\"]]\nfor r in refs:\n    if not r.startswith((\"data:\", \"http://\", \"https://\")):\n        assert Path(r).is_file(), f\"reference missing: {r}\"","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\nresolved = []\nfor ref in refs:\n    if ref.startswith((\"data:\", \"http://\", \"https://\")):\n        resolved.append(ref)\n    else:\n        p = Path(ref).expanduser().resolve()\n        assert p.is_file(), f\"reference missing: {ref}\"\n        resolved.append(str(p))","typeGuard":null,"tryCatchPattern":"try:\n        result = hunyuan_tool.run(inputs)\n    except FileNotFoundError as e:\n        # a reference path does not exist; check spelling/cwd","preventionTips":["Normalize all local references to absolute expanded paths","Keep references inside the pipeline workspace directory","Use https:// URLs for hosted references to bypass local-file handling"],"tags":["hunyuan","reference-image","file-not-found","local-file"],"backgroundTag":null,"analyzedSha":"95e1c3d0ab93482159818560f6a8c8e866b9139f","analyzedAt":"2026-08-15T06:31:20.014Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}