Hmbown/CodeWhale · error · PersistenceBacklogError

the paused channel must retain the newest request and its…

Error message

the paused channel must retain the newest request and its payload

What it means

The paused channel must actually retain at least the newest request and its payload: both retained_queued_requests and estimated_retained_payload_bytes must be strictly positive. This prevents receipts that claim an empty backlog, which would mean the channel dropped work instead of buffering it behind the paused consumer.

Solutions

Confirm the measurement actually pauses the consumer (fixture paused_consumer=true) and re-run the measurement.
Fix the payload estimator so it accounts for the retained request's serialized content.
Regenerate the receipt instead of editing retained_queued_requests or estimated_retained_payload_bytes manually.

Example fix

// before
{"retained_queued_requests": 0, "estimated_retained_payload_bytes": 0}
// after
{"retained_queued_requests": 1, "estimated_retained_payload_bytes": 65536}  # 64 KiB per request

Defensive patterns

Strategy: validation

Validate before calling

def backlog_nonempty(receipt):
    return receipt.get("retained_queued_requests", 0) > 0 and receipt.get("estimated_retained_payload_bytes", 0) > 0

Type guard

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

Try / catch

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

Prevention

Verify the consumer is genuinely paused before the send loop starts.
Smoke-test the payload estimator on a single known 64 KiB request.
Sanity-check that a paused-channel run always leaves at least one queued request.

When it happens

Trigger: Raised by validate_receipt when receipt['retained_queued_requests'] == 0 or receipt['estimated_retained_payload_bytes'] == 0, from validate_baseline_receipt or compare.

Common situations: A measurement run where the channel consumed everything (consumer not actually paused); an estimator bug producing 0 bytes; a truncated or hand-edited receipt.

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

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

Appendix: source

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

    platform = receipt["platform"]
    if not isinstance(platform, str) or platform not in SUPPORTED_PLATFORMS:
        raise PersistenceBacklogError("receipt platform is unsupported")

    attempted = non_negative_integer(receipt["requests_attempted"], "requests_attempted")
    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

View on GitHub (pinned to 433685b202)