nexu-io/open-design · error · SystemExit

job {job_id} is missing source_sha256; ingest visual outputs

Error message

job {job_id} is missing source_sha256; ingest visual outputs with record_imagegen_result.py instead of editing imagegen-jobs.json

What it means

validate_hash requires a source_sha256 on each job; that hash anchors every later integrity check (source vs. output, mirror lineage). The message deliberately points to record_imagegen_result.py because hand-writing a hash bypasses the provenance contract.

Source

Thrown at skills/hatch-pet/scripts/finalize_pet_run.py:62


def default_codex_home() -> Path:
    return Path(os.environ.get("CODEX_HOME") or "~/.codex").expanduser().resolve()


def manifest_path(raw: object, *, run_dir: Path, field: str, job_id: str) -> Path:
    if not isinstance(raw, str) or not raw:
        raise SystemExit(f"job {job_id} has no {field}")
    path = Path(raw).expanduser()
    if not path.is_absolute():
        path = run_dir / path
    return path.resolve()


def validate_hash(job: dict[str, object], *, source: Path, output: Path, job_id: str) -> None:
    expected_hash = job.get("source_sha256")
    if not isinstance(expected_hash, str) or not expected_hash:
        raise SystemExit(
            f"job {job_id} is missing source_sha256; ingest visual outputs with "
            "record_imagegen_result.py instead of editing imagegen-jobs.json"
        )
    if not source.is_file():
        raise SystemExit(f"job {job_id} source image no longer exists: {source}")
    if not output.is_file():
        raise SystemExit(f"job {job_id} decoded output is missing: {output}")
    source_hash = file_sha256(source)
    output_hash = file_sha256(output)
    if source_hash != expected_hash:
        raise SystemExit(f"job {job_id} source image hash does not match imagegen-jobs.json")
    if output_hash != expected_hash:
        raise SystemExit(
            f"job {job_id} decoded output does not match its recorded source image; "
            "do not rewrite decoded visual outputs locally"
        )

View on GitHub (pinned to 5be4028344)

Solutions

Run record_imagegen_result.py against the original ig_*.png to record source_sha256 (and output_path) correctly.
Do not hand-write source_sha256 — it must match the actual file bytes.
Re-run finalize_pet_run.py.

Defensive patterns

Strategy: type-guard

Validate before calling

import json
from pathlib import Path

manifest = json.loads(Path("<run_dir>/imagegen-jobs.json").read_text())
for job in manifest["jobs"]:
    if job.get("status") == "complete":
        assert isinstance(job.get("source_sha256"), str) and job["source_sha256"], \
            f"job {job.get('id')} missing source_sha256 — run record_imagegen_result.py"

Type guard

def job_has_source_hash(job: dict) -> bool:
    return isinstance(job.get("source_sha256"), str) and bool(job["source_sha256"])

Prevention

Never hand-write source_sha256; it must equal the source file bytes.
Use record_imagegen_result.py as the only path to populate hashes.
Validate hashes across all complete jobs before invoking finalize.

When it happens

Trigger: A job marked complete whose source_sha256 is missing, empty, or not a string — typically because the manifest was edited by hand rather than produced by the ingest script.

Common situations: Bypassing record_imagegen_result.py; a manifest from before hashes were required; a botched find-replace that blanked the field.

Related errors

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