Hmbown/CodeWhale · error · RuntimeContractError

{source} schema_version must be {SCHEMA_VERSION}, got {versi

Error message

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

What it means

The schema_version field is missing, boolean, non-integer, or not exactly SCHEMA_VERSION (currently 1). The explicit bool exclusion exists because Python bools are ints. Receipts and budgets must be produced by the same schema generation as the checker, so version skew in either direction fails fast.

Source

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

        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 8880682c63)

Solutions

1. Set "schema_version": 1 as a JSON integer in both the receipt and the budget
2. After upgrading the checker, regenerate receipts and budgets with the matching script version instead of hand-editing
3. Avoid 1.0, "1", and true — the strict type check rejects all of them

Example fix

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

v = doc.get('schema_version')
assert isinstance(v, int) and not isinstance(v, bool) and v == 1, repr(v)

def has_valid_schema_version(doc):
    v = doc.get('schema_version')
    return isinstance(v, int) and not isinstance(v, bool) and v == 1

When it happens

Trigger: Hand-written receipts with "schema_version": "1" (string) or 1.0 (float); a checker upgrade that bumped SCHEMA_VERSION while old receipts or budgets are still in use; mixing in receipts from the persistence script, which uses schema_version 2.

Common situations: Version skew after pulling new checker code; hand-crafted fixtures; JSON encoders that emit floats for whole numbers.

Related errors

• budget schema_version changed
• {source} document_kind must be `{expected_kind}`, got {actua
• {kind} is missing required field `{dotted}`
• GitHub Release ${tag} did not provide an asset inventory
• version must be a semantic release identifier

AI-assisted analysis of Hmbown/CodeWhale@8880682c63 (2026-08-16). Data as JSON: /api/errors/a96336d8d50266be. Report an issue: GitHub.