Getting started

Actual Budget not working: how to find what is wrong

If Actual Budget is not working, isolate the cause step by step: app version, sync, import files and backups. A calm checklist to try before starting over.

Editorial illustration for Actual Budget not working: how to find what is wrong

When a budgeting tool stops working, the problem is almost always one of four things: the app or server version, the sync connection, a file you imported, or the browser or device you are using. Work through them one at a time and write down what changed just before it broke. we cannot see your setup, so treat the steps here as a method and check the project's own documentation for exact menus and commands.

What does "not working" actually mean for you?

Be specific, because the cause depends on the symptom. Pick the closest match before you change anything.

  • It will not open or load at all.
  • It opens but your budget file will not load.
  • Numbers look wrong after an import.
  • Changes on one device do not appear on another.
  • It was fine until an update.

Actual Budget is usually described as open-source, local-first envelope budgeting that can run on the web, on desktop or self-hosted. That mix matters: where your data lives decides which problems are possible. A self-hosted setup adds server and network issues that a desktop-only setup never sees.

How do you isolate the cause?

  1. Back up first. Export or copy your budget file before trying fixes, so a bad fix cannot cost you data.
  2. Note the version of the app and, if you self-host, of the server. A mismatch between the two is a common reason a file stops opening.
  3. Try a different browser or a private window. If it works there, the cause is a browser extension, cache or stored data.
  4. Try a second device. If only one device fails, the fault is local to it.
  5. If you self-host, check that the server is running and reachable from your network before blaming the budget file.

Change one thing at a time. If you update, switch browser and clear data in the same minute, you will never learn which step helped.

Why do numbers look wrong after an import?

Imports fail quietly more often than they fail loudly. Say your bank CSV has 40 rows but only 31 appear. Count both. The nine missing rows often share something: a date written in a different format, an amount with a thousands comma, or a blank description. Say those nine totalled ₹14,250. Your category balances will be off by up to that amount until you find them.

CheckWhat to look for
Row countRows in the file versus rows in the app
Date formatDay first versus month first
Amount columnCommas, currency symbols, brackets for negatives
DuplicatesThe same file imported twice

Should you start again from scratch?

Only as a last resort. A fresh budget file with a clean import often works because it removes accumulated oddities, but you lose history unless you carry over the old data. If the old file still opens, export what you need first.

If the real problem is the setup effort

Sometimes the tool works, but keeping a self-managed system running is more upkeep than you want. If your main goal is simply to see where money went, an app where you upload statements and review rows, such as SpendixAI, avoids servers entirely. It is not an envelope budgeting system, so weigh what you actually need before moving.

How do you record what you tried?

Keep a short log while you troubleshoot. Write the time, what you changed and what happened. Troubleshooting without notes tends to loop: you retry the same fix on day three that failed on day one. A five-line log also makes your help request far more useful, since people answering questions can see what you already ruled out.

  • Version of the app and server before and after any update.
  • Browser or device and whether the problem repeats elsewhere.
  • The exact error text or a description of the odd behaviour.
  • Which budget file, and whether a backup exists.

If an update seems to be the trigger, do not roll back blindly. Check whether the project documents a migration step for your version, and keep the backup safe until you are sure.

Quick recovery checklist

  • Backup taken.
  • Versions noted.
  • Second browser and second device tried.
  • Import row counts compared.
  • Error message saved word for word.
SPENDIXAI JOURNAL

Useful ideas start with a clearer picture of your own spending.

Explore your reports