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

Collect this information before you change settings or delete data:

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

Redact secrets before you share a log with anyone.

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

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

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

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

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.
The vault is locked after a restart - also correct. Unlock it with your passphrase.
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

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

Each guide troubleshoots its own page:

Budget
Editing, review and save - and the per-entity pages (Accounts, Payees, Categories, Tags)
Schedules
Rules
Rule Diagnostics
ActualQL Queries
Budget File Health · Data Browser
Budget File Sync
FX Rates

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.

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.