Troubleshooting

Problems people actually hit running and developing MSaving, and the fix.

Running the stack

I lost the setup code

It’s printed again on every start while the server has no admin: docker compose restart msaving, then docker compose logs msaving.

msaving keeps restarting: the database isn't reachable

The database didn’t come up within two minutes. docker compose logs db. With your own database, check ADMIN_DATABASE_URL (owner login, host reachable from the container, sslmode).

service "secrets" didn't complete successfully

docker compose logs secrets. A traceback there is a bug in the image; with a permissions error, the secrets volume belongs to someone else (it should start empty and be created by Compose).

The Overview fails, or saving a book or profile says the timezone isn’t known

Fixed for aliases like Asia/Saigon (what Windows browsers report): the server maps them to a name the database knows. A database made before that fix may hold an unknown name: on a local test stack, docker compose down -v.

403 origin_not_allowed

The browser is on a different address than the server, for example a copy of the web app served elsewhere, or a proxy that rewrites Host without setting X-Forwarded-Host. Open the web app from the server’s own address. In development, use Vite’s proxy (npm run dev), not VITE_API_URL.

401 not_signed_in on every call

The session ended: 30 days unused, signed out elsewhere, a password change on another device, a reset, or the admin disabled the account. Sign in again. On a fresh database (down -v), old browser sessions are gone too.

403 invite_required or invite_invalid when joining

The server takes new accounts by invite only; the code is wrong, used, revoked or expired. The admin makes a new one (or opens sign-up).

The one-click Update says it’s off, or fails

It needs COMPOSE_PROFILES=updater and docker compose up -d. The page shows the helper’s last error:

• “on a fixed version, not a branch”: the folder is on a release tag (staying on one version); git checkout main to follow releases again.
• A git pull error about local changes: someone edited a file in the folder. Settings belong in .env; git status shows what changed, git stash puts it aside.

docker compose logs updater for more.

The dashboard says some transactions are “not included”

There’s no exchange rate for their currency yet. The daily job fetches rates at start and every day; check docker compose logs msaving | grep fx_update.

Development

dev.sh can’t reach the database on 5433

Something else uses the port, or the compose db was started without docker-compose.dev.yml. dev.sh restarts it with the override; docker compose ps db should show 127.0.0.1:5433->5432.

The web app shows a network error on npm run dev

The API isn’t on 127.0.0.1:8000 (start dev.sh), or set MSAVING_API=http://127.0.0.1:8080 for the compose stack.

Tests

Backup tests fail with a pg_dump version error

Your PATH finds an older pg_dump first. Prefix the test command with PATH=/usr/lib/postgresql/17/bin:$PATH.

Backups fail with an SSL error, with your own database

The database address asks for TLS (?sslmode=require) and the database doesn’t offer it. On a database across the internet, turn TLS on there; on the same machine or a private network, use ?sslmode=disable. Without sslmode, the server uses TLS when the database offers it.