1.43-1.43.1: adding transactions before a balance assignment no longer works, requires -I

[wgslr]

My workflow for reconciling hledger journal with my bank accounts is to add a transaction for today with balance assignments reflecting the current balance of the accounts. Then, I add missed transactions from the past until hledger print -x -ptoday shows all the balance assignment postings to be 0. After upgrading to 1.43, hlegder add prevents me from adding those older transactions unless I use the -I option. It seems that the change "whenever you enter an amount, [hledger add] now checks the journal's balance assertions" incorrectly affects balance assignments as well. Not the first time it turns out I seem to be the only person using balance assignments in hledger 😂

Example

My journal file:

2025-06-01 Transaction 1
    account  100$
    equity   -100$

2025-06-10 Assert balance
    account   ==* 200$
    equity:reconciliation

Failing add, note the date older than the balance assignment:

$ hledger add -f journal.hledger
Date [2025-06-10]: 6-8
Description: Missed transaction
Using this similar transaction for defaults:
2025-06-01 Transaction 1
    account            100$
    equity            -100$

Account 1 [account]:
Amount  1 [100$]: 100$
/home/wojciech/hledger-repro/journal.hledger:6:15:
  | 2025-06-10 Assert balance
6 |     account                         100$ ==* 200$
  |                                          ^^^^^^^^
  |     equity:reconciliation           -100$

Balance assertion failed in account
Across all commodities at this point, including subaccounts, ignoring costs,
the asserted balance is:        200$
but the calculated balance is:  300$
(difference: -100$)
To troubleshoot, check this account's running balance with assertions disabled, eg:
hledger reg -I 'account'

Note as well that this fails even though I'm adding exactly $100, which is the amount missing in the assignment on 2025-06-10. I believe hledger add should succeed in this case regardless of the amount in the added posting.

Version

Running in wsl

$ hledger --version
hledger 1.43.1, linux-x86_64

[simonmichael]

Not the first time it turns out I seem to be the only person using balance assignments in hledger 😂

Because of the downsides.. :-)

But thank you for reporting this, and sorry for breaking your workflow. We did discuss balance assignments as part of #2356, but it looks like we didn't quite finish testing or documenting them in this context. @reesmichael1 I seem to remember a docs update, but I don't see assertions/assignments mentioned at https://hledger.org/dev/hledger.html#add ?

[simonmichael]

To be clear, are you able to work as before by adding -I ?

[simonmichael]

Also just curious, is there any advantage to using a balance assignment here instead of an assertion like

    account                             0 ==* 200$

? It makes the journal usable even when you have not yet caught up with data entry ?

[simonmichael]

And I suppose this is actually a regression. So claim your https://hledger.org/REGRESSIONS.html#regression-finder-bounty within 7 days!

[wgslr]

Thanks for a very quick response!

To be clear, are you able to work as before by adding -I ?

Yes, seems so, although I was lazy about it and quickly reverted to 1.42.

is there any advantage to using a balance assignment here instead of an assertion like

Do you mean that I could then use the assertion error to know when I'm fully caught up?

I'd list the following benefits:

• I can keep using the journal and know my current balances even if I don't have the time to fully catch up with past data entry
• I can run commands during data entry (print, add) without -I
• I can see the incorrect balances for multiple accounts at once, while assertions only print the first wrong one. For example:

In this journal, hledger print -x immediately tells me I'm missing $100 in checking and $2000 in savings:

$ cat hledger.journal
2025-06-01 Transaction 1
    assets:checking  100$
    assets:savings  1000$
    equity   -1100$

2025-06-10 Assign balance
    assets:checking   ==* 200$
    assets:savings   ==* 3000$
    equity:reconciliation

$ hledger print -x -f hledger.journal
2025-06-01 Transaction 1
    assets:checking            100$
    assets:savings            1000$
    equity                   -1100$

2025-06-10 Assign balance
    assets:checking                  100$ ==* 200$
    assets:savings                  2000$ ==* 3000$
    equity:reconciliation          -2100$

With an assertion, I would only see the $100 difference in checking at first and not know if savings balance is correct:

$ cat hledger.journal
2025-06-01 Transaction 1
    assets:checking  100$
    assets:savings  1000$
    equity   -1100$

2025-06-10 Assert balance
    assets:checking  0 ==* 200$
    assets:savings   0 ==* 3000$
    equity:reconciliation

$ hledger print -x -f hledger.journal
hledger: Error: /home/wojciech/hledger-repro2/hledger.journal:7:24:
  | 2025-06-10 Assert balance
7 |     assets:checking                     0 ==* 200$
  |                                           ^^^^^^^^
  |     assets:savings                      0 ==* 3000$
  |     equity:reconciliation               0

Balance assertion failed in assets:checking
Across all commodities at this point, including subaccounts, ignoring costs,
the asserted balance is:        200$
but the calculated balance is:  100$
(difference: 100$)
To troubleshoot, check this account's running balance with assertions disabled, eg:
hledger reg -I 'assets:checking'

Because of the downsides

I do agree I should probably add an explicit 0 ==* $200 after I'm done with reconciliation, to make the journal more explicit and avoid quietly introducing errors later. But the current workflow seems awfully convenient during the data entry.

So claim your bounty

Oh, nice, thank you!

[simonmichael]

That makes sense. Interesting workflow, thanks.