Troubleshooting

Start with prima-bookkeeper doctor. It checks every connection, the tax-rate map, the bank accounts and the document sources, and it names what failed.

A Command Prints Nothing and Never Finishes on macOS

macOS is showing a Keychain dialog that asks whether node may use an item in prima-bookkeeper, and the command waits until someone answers it. A run started by an agent or a schedule waits with nobody to answer.

1. Stop the command with Control and C, then run it again in your own terminal.
2. Watch for the dialog, enter your login password and choose Always Allow.

The dialog also appears when a different Node.js runs the tool from the one that saved the credentials, such as after a Node.js upgrade or with two installs side by side. Run which node, and use that same Node.js for credentials set, auth and keepalive --install.

Messages and What to Do

What you see	What to do
A credential, consent, callback or rate-limit failure	Follow the If It Fails section of the provider’s file in the plugin’s skills/bookkeeper-setup/references/ folder. A lapsed connection needs auth for that provider again, then keepalive --install so it does not recur
No business config at ...	Run init in your workspace, or pass -c with the path to business.json
Could not find a date column on a CSV	The headers are not ones the tool knows. Run csv-inspect, copy bank-formats/generic-debit-credit.json, set your column names, and pass the file with --format or save it in business.json
Contact X is home_tax in Sage but the entry is reverse_charge...	Set the contact’s tax treatment in Sage to rest of world or EU registered, then run post again. Sage works out the reverse charge from the contact
ledger already has probable_duplicate ...	An entry for the same supplier and amount within three days carries no bank id. Check it in your ledger, and if it is the same purchase, record it with link-posting or adopt --accept-probable, then run post again
... the ledger's entry X carries this bank line's id at Y	An entry names this bank line at a different amount. Check it in your ledger, and if you accept the difference, record it with link-posting and a note, then run post again
Money in from supplier X is a refund ...	Sage records a supplier refund as a credit note and a refund allocation, which this version does not post. Enter it in Sage by hand and record it with link-posting
... the ledger's entry X is already recorded against bank line Y	One ledger entry covers two bank lines, such as a deposit and a final payment. Record this line with link-posting, --allocated and --entry-total, then run post again
Timed out after ... waiting for the credential store to return ...	A Keychain dialog was waiting with nobody to answer. Run the command again in your own terminal and choose Always Allow
No ledger account mapped for ...	Add the ledger account id under ledger.accountMap in business.json. init --json prints your ledger’s account list
FreshBooks read-back mismatch on expense	FreshBooks created the expense, but its amount plus tax differs from the bank amount. Check the expense in FreshBooks, correct it there and report what you found

A Post Stopped Partway

The first failure stops the batch, and nothing after it is attempted. Fix what the message names, then run post again for the same batch. The tool skips every entry that already posted, because it checks its own records and your ledger before each one.

A Connection Lapsed

A connection lapses when it goes unused for too long, or when a bank consent reaches its end date. Run prima-bookkeeper auth with the provider’s name, then prima-bookkeeper keepalive --install. doctor reports each connection’s lapse date, so check it before each month.

Getting Help

Getting Help explains how to report a problem. Include the output of prima-bookkeeper doctor and the command you ran, and never include a credential.