{"record":{"id":"8cacbf660824e17b","repo":"nexu-io/open-design","slug":"reference-not-found-source","errorCode":null,"errorMessage":"reference not found: {source}","messagePattern":"reference not found: (.+?)","errorType":"exception","errorClass":"SystemExit","httpStatus":null,"severity":"error","filePath":"skills/hatch-pet/scripts/prepare_pet_run.py","lineNumber":603,"sourceCode":"    run_dir.mkdir(parents=True, exist_ok=True)\n\n    ref_dir = run_dir / \"references\"\n    prompt_dir = run_dir / \"prompts\"\n    row_prompt_dir = prompt_dir / \"rows\"\n    for directory in [\n        ref_dir,\n        prompt_dir,\n        row_prompt_dir,\n        run_dir / \"decoded\",\n        run_dir / \"qa\",\n    ]:\n        directory.mkdir(parents=True, exist_ok=True)\n\n    copied_refs: list[dict[str, object]] = []\n    copied_ref_paths: list[Path] = []\n    for index, source in enumerate(raw_reference_paths, start=1):\n        if not source.is_file():\n            raise SystemExit(f\"reference not found: {source}\")\n        suffix = source.suffix.lower() or \".png\"\n        copied = ref_dir / f\"reference-{index:02d}{suffix}\"\n        shutil.copy2(source, copied)\n        meta = image_metadata(copied)\n        meta[\"source_path\"] = str(source)\n        meta[\"copied_path\"] = str(copied)\n        copied_refs.append(meta)\n        copied_ref_paths.append(copied)\n\n    args.chroma_key = choose_chroma_key(copied_ref_paths, args.chroma_key)\n    layout_guides = create_layout_guides(run_dir)\n\n    request = {\n        \"pet_id\": args.pet_id,\n        \"display_name\": args.display_name,\n        \"description\": args.description,\n        \"created_at\": datetime.now(timezone.utc).isoformat(),\n        \"atlas\": ATLAS,","sourceCodeStart":585,"sourceCodeEnd":621,"githubUrl":"https://github.com/nexu-io/open-design/blob/5be4028344c2eb4c667c5a97bda8f750c5597ef7/skills/hatch-pet/scripts/prepare_pet_run.py#L585-L621","documentation":"Raised inside the reference-copy loop in prepare_pet_run.py when a path passed via --reference does not resolve to a regular file. Each --reference is expanduser()+resolve()'d up front, then source.is_file() is checked before copying into references/reference-NN.<ext>. A missing reference aborts the whole run before any layout/prompt scaffolding is written.","triggerScenarios":"Passing a --reference path that is a directory, a typo, a not-yet-downloaded file, or a path with unexpanded shell variables; relative paths that resolve against an unexpected cwd.","commonSituations":"Reference art lives in a cloud folder that did not finish syncing; teammate hands off a script with a hardcoded /Users/... path; user passes a glob that the shell did not expand.","solutions":["Verify the file exists at the exact path: ls -la <path>.","Confirm it is a file, not a directory: source.is_file() must be true.","Use an absolute path or run from the directory containing the reference; avoid shell variables like $HOME inside the arg.","Re-download or re-export the reference art if it was never materialized."],"exampleFix":"# before\n--reference ~/art/shared/fenrir-concept  # a directory\n# after\n--reference ~/art/shared/fenrir-concept/main.png","handlingStrategy":"validation","validationCode":"from pathlib import Path\nmissing = [p for p in (Path(r).expanduser().resolve() for r in args.reference) if not p.is_file()]\nif missing:\n    raise SystemExit(f\"references not found: {missing}\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Use absolute paths or run from the references' directory.","Add a preflight step in your make target: for r in \"$@\"; do test -f \"$r\" || exit 1; done.","Avoid shell variables inside --reference; expand them before passing."],"tags":["filesystem","cli","hatch-pet","validation"],"backgroundTag":null,"analyzedSha":"5be4028344c2eb4c667c5a97bda8f750c5597ef7","analyzedAt":"2026-08-12T12:03:58.812Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}