Hmbown/CodeWhale · error · PersistenceBacklogError

final_version_applied must be true

Error message

final_version_applied must be true

What it means

final_version_applied must be exactly true: the receipt must assert that the final sent version was applied by the consumer. Combined with applied_version, this proves the paused channel delivered every request with no loss; a false or missing value means the measurement cannot certify end-to-end delivery.

Solutions

1. Ensure the measurement drains the paused consumer fully before writing the receipt, then re-run it.
2. Emit final_version_applied as a strict JSON boolean true, not a string or number.
3. If the consumer cannot apply the final version, fix the delivery bug before measuring the backlog.

Example fix

// before
{"final_version_applied": "true"}
// after
{"final_version_applied": true}

def final_version_flag_valid(receipt):
    return receipt.get("final_version_applied") is True

def is_strict_true(v):
    return v is True

try:
    validate_receipt(receipt)
except PersistenceBacklogError as e:
    print(f"receipt rejected: {e}", file=sys.stderr)
    sys.exit(2)

When it happens

Trigger: Raised by validate_receipt when receipt['final_version_applied'] is not True (False, None, 1, "true"), from validate_baseline_receipt or compare.

Common situations: A harness that stops before unpausing/draining the consumer; serializing the flag as the string "true" or integer 1 instead of a JSON boolean; a consumer crash leaving the drain incomplete.

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

• accepted_requests must equal requests_attempted; sender…
• applied_version is not the final sent version
• estimated_retained_payload_bytes is smaller than the frozen…
• limitations must be a non-empty string array
• retained_queued_requests exceeds accepted_requests

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

Appendix: source

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

        raise PersistenceBacklogError("retained_queued_requests exceeds accepted_requests")
    for field in ("estimated_retained_payload_bytes", "enqueue_elapsed_ns"):
        non_negative_integer(receipt[field], field)
    if retained == 0 or receipt["estimated_retained_payload_bytes"] == 0:
        raise PersistenceBacklogError(
            "the paused channel must retain the newest request and its payload"
        )
    minimum_payload_bytes = retained * FIXTURE["content_bytes_per_request"]
    if receipt["estimated_retained_payload_bytes"] < minimum_payload_bytes:
        raise PersistenceBacklogError(
            "estimated_retained_payload_bytes is smaller than the frozen retained content"
        )
    applied = non_negative_integer(
        receipt["applied_version"], "applied_version"
    )
    if applied != FIXTURE["expected_applied_version"]:
        raise PersistenceBacklogError("applied_version is not the final sent version")
    if receipt["final_version_applied"] is not True:
        raise PersistenceBacklogError("final_version_applied must be true")

    limitations = receipt["limitations"]
    if not isinstance(limitations, list) or not limitations or not all(
        isinstance(item, str) and item for item in limitations
    ):
        raise PersistenceBacklogError("limitations must be a non-empty string array")

    if not isinstance(receipt["rss_supported"], bool):
        raise PersistenceBacklogError("rss_supported must be boolean")
    if receipt["rss_supported"] != (platform == "macos"):
        raise PersistenceBacklogError(
            "rss_supported must be true exactly on the macOS measurement lane"
        )
    rss_fields = RSS_SAMPLE_FIELDS + RSS_DELTA_FIELDS
    if receipt["rss_supported"]:
        for field in rss_fields:
            non_negative_integer(receipt[field], field)
        before = receipt["rss_before_bytes"]

View on GitHub (pinned to 433685b202)