nexu-io/open-design · error · SystemExit

job {job.get('id')} is missing required grounding image(s):

Error message

job {job.get('id')} is missing required grounding image(s): {', '.join(missing)}

What it means

Raised by validate_required_grounding() in record_imagegen_result.py when one or more input_images paths do not resolve to existing files under run_dir. Grounding references must be present on disk so the imagegen job can actually use them; missing files are collected and reported together.

Source

Thrown at skills/hatch-pet/scripts/record_imagegen_result.py:123

def validate_required_grounding(job: dict[str, object], run_dir: Path) -> None:
    if job.get("allow_prompt_only_generation") is not False:
        return
    inputs = job.get("input_images")
    if not isinstance(inputs, list) or not inputs:
        raise SystemExit(
            f"job {job.get('id')} does not list input_images; grounded row jobs must attach references"
        )
    missing = []
    for item in inputs:
        if not isinstance(item, dict) or not isinstance(item.get("path"), str):
            raise SystemExit(f"job {job.get('id')} has an invalid input image entry")
        path = run_dir / item["path"]
        if not path.is_file():
            missing.append(str(path))
    if missing:
        raise SystemExit(
            f"job {job.get('id')} is missing required grounding image(s): "
            + ", ".join(missing)
        )


def update_base_canonical_reference(
    *,
    run_dir: Path,
    output: Path,
    manifest: dict[str, object],
    job: dict[str, object],
    metadata: dict[str, object],
) -> None:
    if job.get("id") != "base":
        return

    canonical = run_dir / CANONICAL_BASE_PATH
    canonical.parent.mkdir(parents=True, exist_ok=True)

View on GitHub (pinned to 5be4028344)

Solutions

1. Record the 'base' job first so references/canonical-base.png exists.
2. Run prepare_pet_run.py --force to repopulate run_dir/references.
3. Verify each path: for p in $(jq -r '.jobs[].input_images[].path' imagegen-jobs.json); do ls run_dir/$p; done.
4. Fix casing/typos in the input_images paths to match the files on disk.

Example fix

# before: base job not yet recorded, references/canonical-base.png missing
# after
record_imagegen_result.py --job-id base --source ~/.codex/generated_images/.../ig_base.png
record_imagegen_result.py --job-id idle --source ~/.codex/generated_images/.../ig_001.png

missing = [str(run_dir / item["path"]) for item in inputs
          if isinstance(item, dict) and isinstance(item.get("path"), str)
          and not (run_dir / item["path"]).is_file()]
if missing:
    raise SystemExit(f"missing grounding images: {missing}")

When it happens

Trigger: input_images points at references/canonical-base.png that was never created (base job not yet recorded); references were deleted after prepare; path is case-mismatched on a case-sensitive filesystem.

Common situations: Recording a row job before the 'base' job (which produces canonical-base.png) was recorded; partial cleanup of run_dir/references; cross-platform path casing.

Related errors

• reference not found: {source}
• file not found: {path}
• row prompt not found: {prompt_path}
• job manifest not found: {path}
• source image not found: {source}

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