nexu-io/open-design · error · SystemExit

reference not found: {source}

Error message

reference not found: {source}

What it means

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.

Source

Thrown at skills/hatch-pet/scripts/prepare_pet_run.py:603

    run_dir.mkdir(parents=True, exist_ok=True)

    ref_dir = run_dir / "references"
    prompt_dir = run_dir / "prompts"
    row_prompt_dir = prompt_dir / "rows"
    for directory in [
        ref_dir,
        prompt_dir,
        row_prompt_dir,
        run_dir / "decoded",
        run_dir / "qa",
    ]:
        directory.mkdir(parents=True, exist_ok=True)

    copied_refs: list[dict[str, object]] = []
    copied_ref_paths: list[Path] = []
    for index, source in enumerate(raw_reference_paths, start=1):
        if not source.is_file():
            raise SystemExit(f"reference not found: {source}")
        suffix = source.suffix.lower() or ".png"
        copied = ref_dir / f"reference-{index:02d}{suffix}"
        shutil.copy2(source, copied)
        meta = image_metadata(copied)
        meta["source_path"] = str(source)
        meta["copied_path"] = str(copied)
        copied_refs.append(meta)
        copied_ref_paths.append(copied)

    args.chroma_key = choose_chroma_key(copied_ref_paths, args.chroma_key)
    layout_guides = create_layout_guides(run_dir)

    request = {
        "pet_id": args.pet_id,
        "display_name": args.display_name,
        "description": args.description,
        "created_at": datetime.now(timezone.utc).isoformat(),
        "atlas": ATLAS,

View on GitHub (pinned to 5be4028344)

Solutions

1. Verify the file exists at the exact path: ls -la <path>.
2. Confirm it is a file, not a directory: source.is_file() must be true.
3. Use an absolute path or run from the directory containing the reference; avoid shell variables like $HOME inside the arg.
4. Re-download or re-export the reference art if it was never materialized.

Example fix

# before
--reference ~/art/shared/fenrir-concept  # a directory
# after
--reference ~/art/shared/fenrir-concept/main.png

from pathlib import Path
missing = [p for p in (Path(r).expanduser().resolve() for r in args.reference) if not p.is_file()]
if missing:
    raise SystemExit(f"references not found: {missing}")

When it happens

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

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

Related errors

• file not found: {path}
• row prompt not found: {prompt_path}
• job manifest not found: {path}
• job {job.get('id')} is missing required grounding image(s):
• source image not found: {source}

AI-assisted analysis of nexu-io/open-design@5be4028344 (2026-08-12). Data as JSON: /api/errors/8cacbf660824e17b. Report an issue: GitHub.