Guide

Check and repair a book

Find and fix splits with no account, unbalanced transactions and broken lots with scrub.checkAndRepair, and know what each repair changed.

A book that came from another program, an import with mistakes, or an old file can contain transactions that do not balance, or splits that point at an account that no longer exists. red-ale refuses to create these, but it can open a book that has them. A scrub finds them and repairs them in the way GnuCash's Check & Repair does, so GnuCash agrees with the result.

Every repair is reported, so you can see what was changed before you save.

What the scrubs do

  • Orphans. A split with no account is moved to an account called Orphan-<currency>, which is created if needed. (scrub.orphans)
  • Imbalances. A transaction whose values do not sum to zero gets one more split, in an account called Imbalance-<currency>, for the difference. The books then balance, and the Imbalance account shows what still needs a real home. (scrub.imbalance)
  • Lots. Splits of a security account are assigned to lots and each lot's capital gains recomputed. (lot.scrub, lot.scrubAccount) See Capital gains with lots.

Steps

  1. Back up first. A repair changes the book in memory, but you will want a copy of the file you started from. Save only after you have looked at the result.
  2. Run it with scrub.checkAndRepair. With no parameters it checks every transaction. Narrow it with account (and subaccounts) or a single transaction. Add lots: true to repair lots too, which GnuCash does not do by default.
  3. Read the repairs. Each has a kind (accountCreated, balanceSplitAdded, and so on) and the transaction, split and account involved. An empty list means the book was clean.
  4. Finish the job by hand. An Imbalance-USD account is a to-do list, not an answer. For each split in it, decide what the money really was, move the split to the right account with transaction.update, and delete the Imbalance account when it is empty (account.delete).
  5. Run it again. A second run reports no repairs.
  6. Save with book.save.

To repair just one transaction, call scrub.imbalance with its transaction GUID.

Example

This GnuCash test book has an unbalanced transaction. The first run adds an Imbalance account and a balancing split; the second finds nothing to do.

Example: with a copy of the gnucash/taxreport example book open as book.gnucash.

JSON-RPC

Request:

{"jsonrpc":"2.0","id":1,"method":"scrub.checkAndRepair","params":{}}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "repairs": [
      {
        "kind": "accountCreated",
        "name": "Imbalance-USD",
        "commodity": "CURRENCY::USD",
        "…": "…"
      },
      {
        "kind": "balanceSplitAdded",
        "…": "…"
      },
      "…"
    ]
  }
}

Request:

{"jsonrpc":"2.0","id":2,"method":"scrub.checkAndRepair","params":{}}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "repairs": []
  }
}

Command line

red-ale exec --book book.gnucash --script - <<'EOF'
scrub.checkAndRepair {}
scrub.checkAndRepair {}
EOF

It prints:

[
  {
    "repairs": [
      {
        "kind": "accountCreated",
        "name": "Imbalance-USD",
        "commodity": "CURRENCY::USD",
        "…": "…"
      },
      {
        "kind": "balanceSplitAdded",
        "…": "…"
      },
      "…"
    ]
  },
  {
    "repairs": []
  }
]

MCP tool call

Tool call:

{"name":"scrub.checkAndRepair","arguments":{}}

Result:

{
  "structuredContent": {
    "repairs": [
      {
        "kind": "accountCreated",
        "name": "Imbalance-USD",
        "commodity": "CURRENCY::USD",
        "…": "…"
      },
      {
        "kind": "balanceSplitAdded",
        "…": "…"
      },
      "…"
    ]
  }
}

Tool call:

{"name":"scrub.checkAndRepair","arguments":{}}

Result:

{
  "structuredContent": {
    "repairs": []
  }
}