Troubleshooting

Starting up

It stays on “Starting engine…”

The engine ships inside the app and starts in a second or two. If it does not:

1. Click Restart Engine in Settings ▸ Advanced.
2. Look at Show Engine Log for the actual error.
3. Download the app again: a damaged copy is the likely cause.

“Could Not Load the Ledger”

The message under it is the reason. The usual ones:

• The app picked the wrong main file (the one that includes the others). Drop the right one on the window: the app then opens that file instead.
• “Operation not permitted”: the ledger reaches outside the folder you chose — an include, a plugin or insert_pythonpath pointing elsewhere. The app can only read that folder. Open the ledger again choosing a folder that contains all of it.
• A plugin of your ledger fails to import. The engine runs from your ledger’s folder, so insert_pythonpath and local plugins work. Besides Beancount’s own plugins it carries autobean; a plugin that needs any other Python package will not find it.
• The file was moved or deleted. Use File ▸ Open Ledger… to find it again.

Try Again restarts the engine and reloads.

“Could Not Open the Ledger”

This one comes before loading, when the app cannot get to the files:

• “… is no longer there”: the main file was deleted, or moved out of its folder. The app forgets that ledger; open it again from File ▸ Open Ledger….
• “… is not inside …”: the file you dropped, or picked as the main file, is not in the folder you allowed. Choose the folder that contains it.

My plugin’s print() output

It cannot break anything — the app keeps its own channel with the engine separate — and you can read it in Settings ▸ Advanced ▸ Show Engine Log.

Numbers

Income shows as positive, unlike in Fava

That is the Show income, liabilities and equity as positive option, on by default. Turn it off in Settings ▸ General to see Beancount’s signs.

An investment shows at cost, or in shares, under “Market Value”

There is no price for that commodity on or before the end of the period. Add a price directive. In Portfolio the cell says no price.

The monthly columns do not add up to the Total

That only happens under Market Value: each column is valued at the prices of its own end date. At Cost and in Units, the columns always add up.

The Balance Sheet shows balances from before the period

As it should: a Balance Sheet is the state at the end of the period, so everything earlier is carried in. The Income Statement is the one that only counts the period. See How the period affects each screen.

A filtered report shows accounts I did not filter by

Filters select whole transactions, with all their postings. See What a filter means for the numbers.

The treemap is missing an account

Treemap and sunburst cannot draw negative totals; a note above the chart says how many accounts were left out.

Does it match Fava and bean-query?

Yes. The numbers are computed by Beancount and Fava’s own code, not re-implemented. If you ever see a difference with the same period, filter and conversion, it is a bug worth reporting.

Saving and Git

Saving did not create a commit

One of the safety rules applied. Most often: the save left Beancount errors, the repository already had uncommitted changes when you opened the ledger, or automatic commits are off. Use File ▸ Commit… (⌥⌘C) to commit by hand. And if the ledger has no history yet, there is nothing to commit to: start one with Start History in History.

The app asks me to review the commit every time I open it

Something in the folder changes on its own between sessions — typically the __pycache__ of your plugins, or files written by a script. Add them to .gitignore.

I committed something by mistake

Within a few seconds: Undo in the toast. Later: use Git from Terminal (git revert, or git reset --soft HEAD~1). The app will pick up the result on its own.

“A merge or rebase is in progress”

Finish or abort it from Terminal (git merge --abort, git rebase --abort). The app will not commit in the middle of one.

Transactions

“This Entry Opens in the Editor”

The dialog only opens transactions it can write back exactly. Entries with comments inside, blank lines in the middle, or generated by pad or a plugin go to the editor. See Faithful to your text.

“Edit” and “Reveal in Editor” are disabled

The entry was generated by a plugin, so it has no line in any file.

The dialog said the ledger had changed

Between opening the dialog and saving, the file was modified (by you in another editor, or by a script), so the app could no longer be sure which lines to replace. Nothing was written. Open the transaction again.

How do I delete a transaction?

In the editor: Reveal in Editor, delete its lines, ⌘S.

iPhone

The Mac says some drafts “had already been imported”

That is the protection against duplicates doing its job: those were written on a previous import.

AirDrop does not open the context in the Companion

Save it to Files instead, then in the Companion choose Ledger ▸ Import Context….

An imported draft is in Errors

It was incomplete — typically one account and one amount, which cannot balance. Click the error, complete the transaction, save.

Starting over

• Restart the engine: Settings ▸ Advanced ▸ Restart Engine.
• Reset everything the app remembers (saved views and recent ledgers included!): quit the app and move ~/Library/Containers/dev.barcia.beancount-desktop to the Trash. The next launch starts as the first one did.

Neither touches your ledger.