Hmbown/CodeWhale · error · PersistenceBacklogError

invalid

Error message

invalid {label} {path}: {error}

What it means

load_json in scripts/check-persistence-backlog-budget.py reads a JSON file and wraps any OSError (missing/unreadable file) or JSONDecodeError (malformed content) into a PersistenceBacklogError with a message identifying the labeled file and the underlying cause. The budget checker treats unreadable or unparseable inputs as fatal so it never silently validates against stale or missing data.

Solutions

1. Check the file exists at the given path (ls <path>) and fix the path/working directory
2. Validate the JSON with python -m json.tool <path> and repair the syntax error
3. Regenerate the receipt/budget file from the producing pipeline
4. Check file permissions if OSError mentions access

Example fix

# before
budget = load_json(Path("budet.json"), "budget")
# after
budget = load_json(Path("budget.json"), "budget")

from pathlib import Path
p = Path("budget.json")
assert p.exists(), f"{p} missing; generate it first"
import json; json.loads(p.read_text())  # raises early with a clear error

try:
    budget = load_json(Path("budget.json"), "budget")
except PersistenceBacklogError as exc:
    print(f"cannot run budget check: {exc}")
    sys.exit(1)

When it happens

Trigger: Calling main with a receipt or budget file path that doesn't exist, has restrictive permissions, or contains invalid JSON (truncated write, trailing comma, HTML error page saved as .json).

Common situations: Running the checker before the receipt file was generated; a partially-written artifact from a crashed pipeline; editing the JSON by hand and introducing a syntax error; wrong relative path when invoking from a different working directory.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Related errors

• Burn rate is optional. When set, it must be a positive $/hr.
• Cargo metadata dependencies for
• Cargo metadata must contain workspace_members and packages…
• Cargo metadata root must be an object
• .annotations is not a valid MCP annotations object

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

Appendix: 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 433685b202)