Hmbown/CodeWhale · error · PersistenceBacklogError

estimated_retained_payload_bytes is smaller than the frozen…

Error message

estimated_retained_payload_bytes is smaller than the frozen retained content

What it means

estimated_retained_payload_bytes must be at least retained_queued_requests * 65536 (the frozen content_bytes_per_request). The payload estimate is a floor, not a guess: each retained request carries at least its frozen 64 KiB content, so a smaller estimate means the estimator undercounts the retained backlog.

Solutions

1. Re-run scripts/measure-persistence-backlog.py so the estimate reflects the current 64 KiB-per-request fixture.
2. Update the payload estimator to include the full serialized request body, not just metadata.
3. If retained_queued_requests changed, recompute the payload minimum as retained * 65536 and confirm the receipt meets it.

Example fix

// before
{"retained_queued_requests": 2, "estimated_retained_payload_bytes": 65536}  # undercounts
// after
{"retained_queued_requests": 2, "estimated_retained_payload_bytes": 131072}  # 2 * 64 KiB

def payload_covers_content(receipt, bytes_per_request=64 * 1024):
    return receipt.get("estimated_retained_payload_bytes", 0) >= receipt.get("retained_queued_requests", 0) * bytes_per_request

def is_non_negative_int(v):
    return isinstance(v, int) and not isinstance(v, bool) and v >= 0

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

When it happens

Trigger: Raised by validate_receipt when receipt['estimated_retained_payload_bytes'] < receipt['retained_queued_requests'] * FIXTURE['content_bytes_per_request'], from validate_baseline_receipt or compare.

Common situations: An estimator changed to count headers only and not body bytes; content_bytes_per_request in the fixture raised without re-measuring; a stale receipt from an older, smaller fixture.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• accepted_requests must equal requests_attempted; sender…
• applied_version is not the final sent version
• final_version_applied must be true
• 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/1002e64ad3b1b748. Report an issue: GitHub.

Appendix: source

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

    accepted = non_negative_integer(receipt["accepted_requests"], "accepted_requests")
    if accepted != attempted:
        raise PersistenceBacklogError(
            "accepted_requests must equal requests_attempted; sender rejection is not backlog improvement"
        )
    retained = non_negative_integer(
        receipt["retained_queued_requests"], "retained_queued_requests"
    )
    if retained > accepted:
        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")

View on GitHub (pinned to 433685b202)