Checking for errors

Last updated: 2024

hledger can check your data in various ways.

Built in checks

In hledger 1.21+, see strict mode and the check command.

Balance assertions

A balance assertion records what an account’s balance should be at a point in time, by writing = EXPECTEDBALANCE after a posting’s amount:

2026-01-31 * paycheck
    income:salary
    assets:checking    $1000 = $1234.56

hledger checks all assertions whenever it reads the journal, and stops with an error, showing the location, if one fails. This protects reconciled balances from being disturbed by later edits or imports, and turns each reconciliation into a permanent check.

Some tips:

• To assert a balance without recording a transaction, use a zero amount: assets:checking $0 = $1234.56.
• = checks just that commodity’s balance in that account. == also checks there are no other commodities, and =* / ==* include subaccounts. See Assertions and subaccounts and neighbouring sections.
• When importing CSV, assign the bank’s running balance to the balance field to generate an assertion on every imported transaction.
• hledger check recentassertions reports accounts whose latest assertion is more than 7 days before their latest posting, a reminder to keep reconciling.
• -I/--ignore-assertions disables the checks temporarily, eg while reorganising old entries.

Old way to check accounts

Here’s another way to check for undeclared accounts, that works with older hledger versions, showing some diff tricks:

$ diff -U0 --label "Unused Accounts" --label "Undeclared Accounts" <(hledger accounts --declared) <(hledger accounts --used)

Compare report output

Save the output of a report, and later use diff to compare the output of the same report, revealing any changes.

$ hledger COMMAND > report.txt
$ hledger COMMAND > report2.txt
$ diff report.txt report2.txt

Or, periodically commit a report’s output into your version control system, then use the VCS to detect any changes since the last commit.

$ hledger COMMAND > report.txt; git add report.txt; git commit -m 'report' report.txt
$ hledger COMMAND > report.txt; git diff -- report.txt

Sometimes new data can cause noisy diffs, especially in tabular reports. To minimise diffs, here are some things to try:

When comparing [balancesheetequity] diffs, do any of these help:

• –layout wide,MAXWIDTH, –layout bare, –layout tidy

• not using tree mode if you’re using that

• not showing multiple periods if you’re using that

• overriding commodity styles with -c, eg limiting precision

• limiting –depth

• -MA –summary

• excluding particular problem accounts/commodities

• generating one report per commodity with cur: ?

• generating csv/tsv/json output ?

• using the balance command instead, and eg –transpose, or a single –period and –format

• using the [a]register command

A pre-commit hook

Version control systems often support a “pre-commit hook”, a script which is required to succeed before each commit. Eg:

#!/bin/bash
set -e
hledger check -s

Flycheck mode

If you use Emacs, you can configure flycheck to run your preferred checks when you edit a journal file. This integration is currently quite basic, but it still gives very useful real-time feedback. Setup tips:

• in Emacs, install the flycheck-hledger package and customise the flycheck-checkers variable, adding hledger to the list
• customise the flycheck-hledger-strict and flycheck-hledger-checks variables

Todo / maybe

Here are some checks we don’t support, but could:

• accountsactive - for each account used, if there is posting with an open: tag, it must have a corresponding posting with a close: tag, and all other postings must be chronologically between (and if on the same date, textually between) open and close postings. (“Accounts are posted to only within their declared active period.”)
• explicitamounts - all transaction amounts have been recorded explicitly

Preventing postings to closed accounts

Some options (from https://www.reddit.com/r/plaintextaccounting/comments/180a11b/how_to_represent_closure_of_an_account_using):

1. Add a balance assertion when the account is closed, and then use hledger check recentassertions (https://hledger.org/1.31/hledger.html#other-checks). After a week has passed, new postings to it (without a new, correct, balance assertion) will raise an error.

2. Add a zero balance assertion in the far future. Eg:

   12000-01-01 * This balance shall remain zero for ten thousand years assets:foo2022 0 ==* 0

3. (If yearly granularity is ok:) Use a new journal file and new account declarations, and drop the obsolete accounts, each year. Strict mode or hledger check accounts will warn of any new references to the old account.

4. (If you are comfortable with unix tools:) Make a custom check script, eg grep the output of hledger reg OLDACCT for inappropriate dates.

5. https://hledger.org/scripts.html#hledger-check-fancyassertions might help.

6. support account lifetimes ? #1389 is the place to work on better support for this.