Troubleshooting

Errors print on stderr as Error: …, and the command exits with status 1. To see the full technical detail, including the Actual engine's own logging, run the command again with FOB_DEBUG=1:

FOB_DEBUG=1 fob-actual accounts list

Session token is invalid or expired#

Error: Session token is invalid or expired. Run `fob-actual auth login` to store a fresh one. See …

Sign in again: fob-actual auth login --profile <name> (add --password for a password server). The profile keeps its server and budget. Tokens expire only if your server is set to expire them (ACTUAL_TOKEN_EXPIRATION).

Could not reach the Actual server#

Error: Could not reach the Actual server. Check the server URL and your connection. See …

Check the URL opens Actual in your browser. Use the base address, such as https://budget.example.com, without a path.
fob-actual config profiles list shows the URL each profile uses. Fix it with config profiles add <name> --server-url <url>.
If the server is on your home network or behind a VPN, the machine running fob-actual must be able to reach it too.

Error: Password login failed (invalid-password). If this server uses OpenID, omit --password and paste a browser token instead.

Check the password. If your server signs in with OpenID, there's no password: follow Sign in with OpenID.

Budget not found#

Error: Budget not found on the server. Check the sync id with `fob-actual budgets list`. See …

The profile's sync ID doesn't match a budget this token can see. Run fob-actual budgets list, then fob-actual config profiles add <name> --sync-id <id> with the right one.

No budget selected#

Error: No budget selected. Set one with `fob-actual config profiles add <name> --sync-id <id>` (list them with `fob-actual budgets list`).

The server has several budgets and the profile isn't bound to one yet. See Choose a budget.

No Actual profile selected#

Error: No Actual profile selected. Run `fob-actual auth login --server-url <url>` to connect, or `fob-actual config profiles add <name>` (or set FOB_ACTUAL_* env). See …

Follow Connect your budget. For environment variables, both FOB_ACTUAL_SERVER_URL and FOB_ACTUAL_SESSION_TOKEN must be set.

Encrypted budgets#

Error: This budget is end-to-end encrypted. Set the encryption password on the profile (`fob-actual config profiles add <name> --encryption-password ...`). See …

Add the budget's encryption password, the one you set in Actual when you turned on encryption:

fob-actual config profiles add household --encryption-password "<encryption password>"

Account name is ambiguous#

Error: Account name 'Checking' is ambiguous (2 matches). Use the id instead: …

Two accounts share that name (names match without regard to case). Use one of the IDs it lists, or rename an account in Actual.

Refusing to delete without --yes#

Deleting accounts, transactions, categories, payees and the rest needs --yes (-y). This stops a script deleting by accident. Run it with --dry-run first to see what would change.

Changes don't show in the Actual app#

Writes sync to the server when the command finishes; reload Actual in your browser to see them. In the other direction, every fob-actual command fetches the latest changes from the server when it starts.

Still stuck?#

Open an issue on GitHub with the command, the error text, your Actual server version (fob-actual server info) and your Node.js version. Leave out tokens, passwords and real account data.