Hmbown/CodeWhale · error · RuntimeContractError

schema_version must be , got

Error message

{source} schema_version must be {SCHEMA_VERSION}, got {version!r}

What it means

validate_document requires `schema_version` to be the integer SCHEMA_VERSION (currently 1) — booleans are explicitly rejected. Any missing, non-integer, boolean, or wrong-version value raises this RuntimeContractError, guarding against consuming documents produced by an incompatible schema version.

Solutions

1. Set `"schema_version": 1` (plain integer) in the document to match the checker's SCHEMA_VERSION.
2. If the file is from an incompatible tool version, regenerate it with the current measure/checker scripts instead of editing the version by hand.
3. Ensure the producer serializes the version as a JSON number, not a string or boolean.

Example fix

// before
{"document_kind": "...", "schema_version": "1"}
// after
{"document_kind": "...", "schema_version": 1}

import json
from pathlib import Path
doc = json.loads(Path(path).read_text(encoding="utf-8"))
version = doc.get("schema_version")
if isinstance(version, bool) or not isinstance(version, int) or version != 1:
    raise SystemExit(f"{path}: schema_version must be 1, got {version!r}")

def has_valid_schema_version(doc, expected: int = 1) -> bool:
    v = doc.get("schema_version") if isinstance(doc, dict) else None
    return not isinstance(v, bool) and isinstance(v, int) and v == expected

try:
    validate_document(doc, RECEIPT_KIND, "receipt")
except RuntimeContractError as e:
    if "schema_version" in str(e):
        print("regenerate the document with the current tool version")
    raise

When it happens

Trigger: A receipt/budget JSON with schema_version 0, 2, "1", 1.0, true, or the field missing entirely.

Common situations: Documents generated by an older/newer version of the tool after a schema bump; hand-edited files where the version was mistyped as a string or removed; YAML-to-JSON conversion that turned 1 into "1" or true.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• invalid : top level must be an object
• measurement receipt must be an object
• document_kind must be ` `, got
• Automation run schema v
• Automation schema v is newer than supported v

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

Appendix: source

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

        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)
        or not isinstance(version, int)
        or version != SCHEMA_VERSION
    ):
        raise RuntimeContractError(
            f"{source} schema_version must be {SCHEMA_VERSION}, got {version!r}"
        )


def required_value(document: dict[str, Any], path: MetricPath, kind: str) -> Any:
    value: Any = document
    dotted = ".".join(path)
    for part in path:
        if not isinstance(value, dict) or part not in value:
            raise RuntimeContractError(f"{kind} is missing required field `{dotted}`")
        value = value[part]
    return value


def tool_identity_digest(names: list[str]) -> str:
    return hashlib.sha256("\0".join(names).encode("utf-8")).hexdigest()

View on GitHub (pinned to 433685b202)