Hmbown/CodeWhale · error · PersistenceBacklogError

limitations must be a non-empty string array

Error message

limitations must be a non-empty string array

What it means

limitations must be a non-empty array of non-empty strings. Every receipt must document the known caveats of its measurement (e.g. platform-specific RSS limits); an empty, non-list, or blank-string limitations field means the receipt omits required disclosure about measurement validity.

Solutions

  1. Re-run the measurement script so limitations is emitted with its documented caveat strings.
  2. If editing a receipt, keep limitations as a list of non-empty strings, e.g. ["RSS sampling unsupported on this platform"].
  3. Fix generator code that serializes limitations as null or joins them into a single string.

Example fix

// before
"limitations": []
// after
"limitations": ["rss deltas are clamped at zero; allocator reuse can mask growth"]
Defensive patterns

Strategy: validation

Validate before calling

def limitations_valid(receipt):
    lim = receipt.get("limitations")
    return isinstance(lim, list) and len(lim) > 0 and all(isinstance(x, str) and x for x in lim)

Type guard

def is_non_empty_str_array(v):
    return isinstance(v, list) and len(v) > 0 and all(isinstance(x, str) and x for x in v)

Try / catch

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

Prevention

When it happens

Trigger: Raised by validate_receipt when receipt['limitations'] is not a list, is an empty list, or contains a non-string or empty-string element, from validate_baseline_receipt or compare.

Common situations: A regenerated receipt that drops the limitations block; tools writing None instead of a list; copying a receipt template and blanking the limitation strings.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

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

Appendix: source

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

        )
    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"]
        if receipt["rss_during_delta_bytes"] != max(
            0, receipt["rss_during_bytes"] - before
        ):
            raise PersistenceBacklogError("rss_during_delta_bytes is inconsistent")
        if receipt["rss_after_delta_bytes"] != max(
            0, receipt["rss_after_bytes"] - before

View on GitHub (pinned to 433685b202)