Hmbown/CodeWhale · error · PersistenceBacklogError

receipt {field} must be a version string

Error message

receipt {field} must be a version string

What it means

Raised in validate_receipt (scripts/check-persistence-backlog-budget.py:159-161) when rustc_version or cargo_version is not a string or does not start with "rustc " / "cargo ". The checker stores the full first line of `rustc --version` / `cargo --version` output so receipts are pinned to the exact toolchain and can be compared verbatim against the live toolchain later.

Source

Thrown at scripts/check-persistence-backlog-budget.py:161

    if missing:
        raise PersistenceBacklogError(
            "receipt missing required field(s): " + ", ".join(missing)
        )
    if receipt["document_kind"] != RECEIPT_KIND:
        raise PersistenceBacklogError(f"receipt document_kind must be {RECEIPT_KIND}")
    if receipt["schema_version"] != SCHEMA_VERSION:
        raise PersistenceBacklogError("receipt schema_version changed")
    for field, expected in FIXTURE.items():
        validate_frozen_field(field, receipt[field], expected)
    if not isinstance(receipt["source_sha"], str) or not SOURCE_SHA_PATTERN.fullmatch(
        receipt["source_sha"]
    ):
        raise PersistenceBacklogError("receipt source_sha must be an exact lowercase Git SHA")
    if type(receipt["source_dirty"]) is not bool:
        raise PersistenceBacklogError("receipt source_dirty must be boolean")
    for field, prefix in (("rustc_version", "rustc "), ("cargo_version", "cargo ")):
        if not isinstance(receipt[field], str) or not receipt[field].startswith(prefix):
            raise PersistenceBacklogError(f"receipt {field} must be a version string")
    validate_frozen_field("build_profile", receipt["build_profile"], "test")
    validate_frozen_field("sample_count", receipt["sample_count"], 1)
    if expected_source is not None:
        for field in (
            "source_sha",
            "source_dirty",
            "rustc_version",
            "cargo_version",
            "build_profile",
            "sample_count",
        ):
            if receipt[field] != expected_source[field]:
                raise PersistenceBacklogError(
                    f"receipt {field} does not match the checked source"
                )
    if require_clean_source and receipt["source_dirty"]:
        raise PersistenceBacklogError("persistence measurement source tree is dirty")
    platform = receipt["platform"]

View on GitHub (pinned to 8880682c63)

Solutions

1. Regenerate the receipt so toolchain strings are captured verbatim from `rustc --version` / `cargo --version`.
2. Ensure the Rust test writes the env-provided string unchanged rather than reformatting it.
3. Run the check with the same toolchain (rustup default / +toolchain) used for measurement.

Example fix

// receipt (before)
"rustc_version": "1.75.0"
// receipt (after)
"rustc_version": "rustc 1.75.0 (82e1608dfa6f9b55c8a34c4193a27fe0ba1620f3 2023-12-21)"

for field, prefix in (("rustc_version", "rustc "), ("cargo_version", "cargo ")):
    v = receipt.get(field)
    if not isinstance(v, str) or not v.startswith(prefix):
        sys.exit(f"{field} malformed; store full `--version` output verbatim")

def is_version_string(value, prefix: str) -> bool:
    return isinstance(value, str) and value.startswith(prefix)

try:
    validate_receipt(receipt)
except PersistenceBacklogError as e:
    if "must be a version string" in str(e):
        raise RuntimeError("toolchain string reformatted; recapture raw --version output") from e
    raise

When it happens

Trigger: Storing only the bare version ("1.75.0") without the leading program name; empty or null values; a wrapper/proxy toolchain whose --version output starts differently; cross-compile setups where the captured output came from a different binary.

Common situations: Custom rustc wrappers in CI; receipts from env plumbing (CODEWHALE_TEST_PERSISTENCE_BACKLOG_RUSTC_VERSION) that stripped the prefix; hand-filled provenance.

Related errors

• source provenance command failed: {' '.join(command)}
• receipt source_sha must be an exact lowercase Git SHA
• receipt source_dirty must be boolean
• receipt {field} does not match the checked source
• baseline provenance needs {field}

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