Skip to content
Actual BenchActual Bench

Troubleshooting

Use this page for common installation, connection, storage, and staged-change problems. Each feature guide also includes troubleshooting for feature-specific issues.

Troubleshoot safely: collect basic information

Section titled “Troubleshoot safely: collect basic information”

Collect this information before you change settings or delete data:

  1. The Actual Bench version (sidebar footer).
  2. The connection mode (Direct Actual Server or HTTP API Server).
  3. The active budget/connection (top bar).
  4. What App Health reports.
  5. The browser console, if it says anything useful.
  6. Container logs.
  7. The smallest thing you can do that makes it happen again.

Redact secrets before you share a log with anyone.

Installation and container

Section titled “Installation and container”
  • The container exits immediately - read the logs. Usually the image tag or a /data volume that cannot be mounted.
  • Port conflict - something else has that port. Publish on a different one.
  • Wrong architecture - the images cover amd64 and arm64. Make sure your host pulls its own.
  • The proxy returns 502 or 504 - it cannot reach the container, or is not forwarding the host and protocol headers. See Deployment.

Metadata database

Section titled “Metadata database”
  • Not writable - App Health says Writable = No. Check the /data permissions and ownership.
  • The history is empty and should not be - /data is unmounted, or points somewhere new. Check ACTUAL_BENCH_DB_PATH.
  • Migration issue after upgrade - see Upgrading and Backups.

Direct connection

Section titled “Direct connection”
  • The browser cannot reach Actual Server - open that URL in the same browser, over HTTPS, and see what happens.
  • CORS or cross-origin isolation errors - allow CORS, or serve Actual Server same-origin through your proxy. Bench sets its own isolation headers already; if a proxy strips them, Direct mode reports that clearly and you can use HTTP API Server mode instead.
  • An encrypted budget will not open - check the Encryption password. It is not the server password.

HTTP API connection

Section titled “HTTP API connection”
  • fetch failed or 502 Bad Gateway - the Bench container cannot reach actual-http-api. Check the network between them, and remember localhost means Bench itself.
  • Wrong URL or API key - verify the HTTP API Server URL and that the API Key matches ACTUAL_API_KEY.

Browser state

Section titled “Browser state”
  • A recent connection still asks for the password - correct. Recent details hold no secrets. Use the remembered-server vault if you want the credential kept.
  • Signed out after a restart - also correct. Sign in again; your saved connections open with it.
  • Remembered servers are gone - the metadata database or the /data volume was replaced. Whoever runs the server needs to check the deployment and restore a backup.
  • A refresh loses the connection - memory-only connections do that by design.
  • A stale worker or cache in Direct mode - clearing this site’s browser data fixes it, and costs you your saved presets and a reconnect. Last resort.

Staged changes and Save

Section titled “Staged changes and Save”
  • Changes did not persist - either you did not press Save, or some items failed. Failures stay marked, with a retry.
  • A note will not discard - notes saved the moment you wrote them. See Work safely.
  • A carryover toggle is not in the draft - it never was. Carryover writes immediately.
  • The wrong budget changed - drafts are per connection. Check which one is active before you save.

Feature areas

Section titled “Feature areas”

Each guide troubleshoots its own page:

Performance

Section titled “Performance”

Slowness is nearly always size:

  • Entity pages load everything. A very large budget drags on Accounts, Payees, Categories and Rules.
  • The full SQLite integrity check is slow. So is exporting a huge table.
  • Big sync previews and diagnostics over a large rule set do real work.
  • A very large snapshot is limited by your browser’s memory.

Loan Apply or Undo split is slow on a Direct connection

Section titled “Loan Apply or Undo split is slow on a Direct connection”

To see where the time goes, turn on the console timing flags, reload, reconnect and repeat the action. Paste this in the browser console:

localStorage.setItem("ab:debug-timing", "1");
localStorage.setItem("ab:debug-sqlite-files", "1");

The console then reports how long the budget open, each read, the write and the checks after it take. It logs no paths, account or transaction identifiers, credentials or amounts. Logging adds overhead, so treat a traced run as an investigation, not a benchmark. If the console says tracing is unavailable, your Actual API build is not one the trace supports; the timings still work.

To turn it off, remove both flags, reload and reconnect:

localStorage.removeItem("ab:debug-timing");
localStorage.removeItem("ab:debug-sqlite-files");

Reporting a bug

Section titled “Reporting a bug”

Open an issue on GitHub. Include:

  • Actual Bench version, browser, and OS.
  • Connection mode and deployment type.
  • Steps to reproduce, and what you expected instead.
  • Screenshots, and redacted console or container logs.
  • Whether it happens in the demo, or in another browser.
Section titled “Related pages”