Hmbown/CodeWhale · error · RuntimeContractError

missing

Error message

missing {kind}: {path}

What it means

load_json in check-runtime-contract-budget.py reads a JSON document (a receipt via --receipt or the budget file) and wraps FileNotFoundError in a RuntimeContractError with this message. It means the script was asked to validate a JSON file that does not exist on disk.

Solutions

1. Check the path in the message; run the script from the repo root or pass the correct --receipt path.
2. If the receipt should exist, generate it first (run the checker without --receipt, or `measure-runtime-contract.py`, possibly with --update).
3. Restore the missing scripts/runtime-contract-budget.json if it was deleted (git checkout -- scripts/runtime-contract-budget.json).

Example fix

// before
python3 scripts/check-runtime-contract-budget.py --receipt reciept.json
// after
python3 scripts/check-runtime-contract-budget.py --receipt receipt.json

from pathlib import Path
receipt = Path("receipt.json")
if not receipt.is_file():
    raise SystemExit(f"receipt not found: {receipt}")

def receipt_exists(path) -> bool:
    from pathlib import Path
    return Path(path).is_file()

try:
    run_checker(["--receipt", str(path)])
except RuntimeContractError as e:
    if str(e).startswith("missing"):
        generate_receipt(path)  # or fix the path
    else:
        raise

When it happens

Trigger: Running `check-runtime-contract-budget.py --receipt <path>` where <path> does not exist, or the default budget file scripts/runtime-contract-budget.json being absent from the checkout.

Common situations: Typo in the --receipt path; running the script outside the repo root after moving it; a fresh clone or CI job where the receipt artifact was never produced/downloaded; .gitignore deleting the generated receipt.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• invalid
• bundle at is bytes; the limit is bytes
• Cannot parse portable data; use JSON for OpenCode or plain…
• Cargo metadata is not valid JSON
• Cargo metadata must contain workspace_members and packages…

AI-assisted analysis of Hmbown/CodeWhale@433685b202 (2026-09-15). Data as JSON: /api/errors/ea85d39fd85a2b73. Report an issue: GitHub.

Appendix: source

Thrown at scripts/check-runtime-contract-budget.py:164

    *(
        (
            ("representative_context", "stages", stage, "identity_sha256"),
            f"representative {label} stage identity digest",
        )
        for stage, label in REPRESENTATIVE_STAGES
    ),
)


class RuntimeContractError(ValueError):
    """A receipt or budget is missing a required, well-typed metric."""


def load_json(path: Path, kind: str) -> dict[str, Any]:
    try:
        document = json.loads(path.read_text(encoding="utf-8"))
    except FileNotFoundError as error:
        raise RuntimeContractError(f"missing {kind}: {path}") from error
    except (OSError, json.JSONDecodeError) as error:
        raise RuntimeContractError(f"invalid {kind} {path}: {error}") from error
    if not isinstance(document, dict):
        raise RuntimeContractError(f"invalid {kind} {path}: top level must be an object")
    return document


def validate_document(
    document: dict[str, Any], expected_kind: str, source: str
) -> None:
    actual_kind = document.get("document_kind")
    if actual_kind != expected_kind:
        raise RuntimeContractError(
            f"{source} document_kind must be `{expected_kind}`, got {actual_kind!r}"
        )
    version = document.get("schema_version")
    if (
        isinstance(version, bool)

View on GitHub (pinned to 433685b202)