Hmbown/CodeWhale · error · PersistenceBacklogError

receipt missing required field(s)

Error message

receipt missing required field(s): <joined missing fields>

What it means

`validate_receipt` checks that every field in `REQUIRED_RECEIPT_FIELDS` is present in a persistence backlog receipt. If any of the ~29 required fields (document_kind, schema_version, source_sha, RSS counters, fixture fields, etc.) are absent from the JSON object, this error lists the missing names. The receipt format is a frozen contract, so a partial receipt is rejected before any value-level validation.

Solutions

1. Regenerate the receipt by running the measurement script (`check-persistence-backlog-budget.py` without --receipt) instead of hand-authoring it
2. Add the fields named in the error message to the receipt JSON, copying values from a fresh measurement run
3. Check `scripts/persistence-backlog-baseline-receipt.json` as a reference for the full required field set
4. Upgrade the receipt producer (scripts/measure-persistence-backlog.py) so it emits the current schema

Example fix

// before (receipt.json)
{"document_kind": "codewhale.persistence_backlog_receipt", "schema_version": 2}
// after
{"document_kind": "codewhale.persistence_backlog_receipt", "schema_version": 2, "source_sha": "...", "source_dirty": false, "rustc_version": "rustc 1.0", "cargo_version": "cargo 1.0", "build_profile": "test", "sample_count": 1, "platform": "linux", "limitations": ["..."], "accepted_requests": 128, "requests_attempted": 128}

REQUIRED = ("document_kind","schema_version","source_sha","source_dirty","rustc_version","cargo_version","build_profile","sample_count","fixture_id","platform","request_variant","payload_estimator","paused_consumer","requests_attempted","content_bytes_per_request","single_session_id","expected_applied_version","accepted_requests","retained_queued_requests","estimated_retained_payload_bytes","applied_version","final_version_applied","enqueue_elapsed_ns","rss_supported","rss_before_bytes","rss_during_bytes","rss_after_bytes","rss_during_delta_bytes","rss_after_delta_bytes","limitations")
missing = [f for f in REQUIRED if f not in receipt]
assert not missing, f"missing fields: {missing}"

def is_complete_receipt(r):
    return isinstance(r, dict) and all(f in r for f in ("document_kind","schema_version","source_sha","platform","limitations"))

try:
    validate_receipt(receipt)
except PersistenceBacklogError as e:
    if str(e).startswith("receipt missing required field"):
        receipt = regenerate_receipt()

When it happens

Trigger: Passing `--receipt <path>` with a JSON file that omits required keys; hand-editing a receipt and deleting a field; an older measurement script producing a schema with fewer fields; feeding the baseline receipt from another project.

Common situations: Receipts written by an older schema version before new fields (e.g. rss_during_delta_bytes) were added; a user copying a receipt template and dropping fields; JSON manually trimmed to shrink a diff.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• receipt document_kind must be
• invalid : top level must be an object
• must be a JSON object
• receipt schema_version changed
• receipt source_dirty must be boolean

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

Appendix: source

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

        "source_dirty": bool(
            run(["git", "status", "--porcelain", "--untracked-files=normal"])
        ),
        "rustc_version": run(["rustc", "--version"]),
        "cargo_version": run(["cargo", "--version"]),
        "build_profile": "test",
        "sample_count": 1,
    }


def validate_receipt(
    receipt: dict[str, Any],
    *,
    expected_source: dict[str, Any] | None = None,
    require_clean_source: bool = False,
) -> None:
    missing = [field for field in REQUIRED_RECEIPT_FIELDS if field not in receipt]
    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")

View on GitHub (pinned to 433685b202)