Skip to main content

LINT.DEBT.LEDGER_UNREADABLE — the account exists and this build cannot act on it

  • Category: safety
  • Level: 0
  • Stability: stable
  • Suites: lint

The debt ledger is present and this build cannot use it — malformed JSON, a shape it does not recognize, or a schema version newer than the one it writes.

Why this is undetermined and not a pass​

This is the one place a tool is most tempted to assume the comfortable thing. "No file, no debts" and "broken file, no debts" both produce a clean report — at exactly the moment nobody can say whether the project is clean. A skip without a reason is a bug; this is that reason, named.

The usual causes​

  • A newer SQLens wrote it. The schema version is explicit precisely so an older build says so instead of guessing. Upgrade, or check out the branch that matches the file.
  • A merge left conflict markers in it. The ledger is designed to merge cleanly — one entry per block, deterministically sorted — but a hand-edit during a conflict can still break the JSON.
  • The path points somewhere else. deploy.debt.path is repository-relative; a run from a different working directory reads a different file.

Raising an old ledger to the current schema​

The schema field is the contract, and it exists so this never has to be guessed at. Today's version is 1 — the only one this build writes and the only one it reads.

A file written by a newer SQLens is not something an older build can convert: it may contain fields this one has never heard of, and dropping them silently would be the data loss the version check exists to prevent. Upgrade the package instead.

Going the other way — an older file into a newer build — is what a future migration note will describe, per version, in the release the change ships in. Until a second schema version exists there is nothing to convert, and this section will say so rather than invent a procedure nobody has tested.

If a file is genuinely beyond repair, the safe reset is to delete it and run sqlens:lint --debt=record. That rebuilds the account from what the project owes today — every first_seen restarts at that date, and every acknowledgment and its written reason is gone. It is a real loss of history, so it is the last option, not the first.

What it does NOT mean​

It does not mean the run failed. Every other rule still ran and every other finding still stands; only the debt account could not be consulted.