Hmbown/CodeWhale · error · PersistenceBacklogError

invalid {label} {path}: {error}

Error message

invalid {label} {path}: {error}

What it means

scripts/check-persistence-backlog-budget.py loads two JSON documents — the budget (scripts/persistence-backlog-budget.json) and the baseline receipt (scripts/persistence-backlog-baseline-receipt.json). load_json wraps their reading/parsing; this error means the file could not be read (OSError: missing, unreadable) or its text was not valid JSON (JSONDecodeError). The underlying error text is appended, and the exception type is PersistenceBacklogError (a ValueError).

Source

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

    "enqueue_elapsed_ns",
    "rss_during_delta_bytes",
    "rss_after_delta_bytes",
)
RSS_SAMPLE_FIELDS = ("rss_before_bytes", "rss_during_bytes", "rss_after_bytes")
RSS_DELTA_FIELDS = ("rss_during_delta_bytes", "rss_after_delta_bytes")
SUPPORTED_PLATFORMS = {"linux", "macos", "windows"}
SOURCE_SHA_PATTERN = re.compile(r"[0-9a-f]{40}")


class PersistenceBacklogError(ValueError):
    """A receipt or budget broke the measurement contract."""


def load_json(path: Path, label: str) -> dict[str, Any]:
    try:
        value = json.loads(path.read_text(encoding="utf-8"))
    except (OSError, json.JSONDecodeError) as error:
        raise PersistenceBacklogError(f"invalid {label} {path}: {error}") from error
    if not isinstance(value, dict):
        raise PersistenceBacklogError(f"{label} must be a JSON object")
    return value


def non_negative_integer(value: Any, field: str) -> int:
    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
        raise PersistenceBacklogError(f"{field} must be a non-negative integer")
    return value


def validate_frozen_field(field: str, value: Any, expected: Any) -> None:
    if type(value) is not type(expected) or value != expected:
        raise PersistenceBacklogError(
            f"receipt {field} must remain {expected!r}, got {value!r}"
        )

View on GitHub (pinned to 8880682c63)

Solutions

1. Read the appended error detail: 'No such file or directory' means regenerate/restore the file; 'Expecting ...' points at the JSON syntax offset.
2. Validate the file standalone: python3 -m json.tool scripts/persistence-backlog-budget.json > /dev/null.
3. Regenerate the baseline receipt with the project's documented measurement step so the file exists and is complete.
4. Fix any merge-conflict markers or trailing commas, then re-run the check.

Example fix

# before: budget.json with a trailing comma
{"max_files": 5000,}
# after
{"max_files": 5000}

import json
from pathlib import Path

def json_document_loads(path: Path) -> bool:
    try:
        json.loads(path.read_text(encoding="utf-8"))
        return True
    except (OSError, json.JSONDecodeError):
        return False

from scripts.check_persistence_backlog_budget import PersistenceBacklogError

try:
    budget = load_json(BUDGET_PATH, "budget")
except PersistenceBacklogError as error:
    logger.error("budget document unreadable: %s", error)
    raise SystemExit(2)  # fail the CI step, do not fall back to defaults

When it happens

Trigger: Running the checker when either JSON file is absent (fresh clone where the baseline receipt was never generated), truncated by an interrupted write, or contains a syntax error such as a trailing comma or single quotes. The label in the message tells you which file ('budget' vs 'baseline receipt').

Common situations: CI running the budget check before the receipt-generation step; hand-editing the budget JSON and leaving invalid syntax; a merge conflict resolved with conflict markers still inside the JSON; line-ending or BOM issues from Windows editors.

Related errors

• {label} must be a JSON object
• {field} must be a non-negative integer
• {path}:{lineno}: expected 'alias = Name <email>'
• baseline provenance build profile/sample count changed
• {kind} field `{dotted_names}` must be sorted unique non-empt

AI-assisted analysis of Hmbown/CodeWhale@8880682c63 (2026-08-16). Data as JSON: /api/errors/24534c35f2e4fcd6. Report an issue: GitHub.