docs / troubleshooting / common-issues.md

Troubleshooting & Common Issues

This page collects practical problems and how to resolve them.

Use the in-app chat or an external model with these docs loaded for more context-specific help.

First Admin / Bootstrap Problems

"No admin exists" or keeps redirecting to create admin

This is expected on a completely fresh database.
Make sure the first user creation succeeded (check browser console or server logs).
Local development: instant email via /api/auth/dev (no SMTP).
Production: configure SMTP and/or OAuth first; magic link or Google/Microsoft after bootstrap. Instant email returns 403.
After the first ADMIN is created, this screen should not appear again.

Bootstrap form does nothing or errors

Check that the database is reachable (DATABASE_URL correct).
Run migrations: npx prisma migrate deploy in production/Docker (migrate dev is fine for local non-Docker).
Look at server logs for Prisma or auth errors.

Sign-in / OAuth / Magic link

OAuth buttons missing

Set GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET and/or Microsoft Entra ID pair in the app environment and restart.
Register redirect URIs: {AUTH_URL}/api/auth/callback/google and .../microsoft-entra-id.

Access denied after OAuth

New users need an active invitation for that exact email (after bootstrap).
The Google/Microsoft account email must match the invite (case-insensitive).
Disabled users cannot sign in.

Magic link never arrives / invalid

Require full SMTP trio: SMTP_HOST, SMTP_USER, SMTP_PASS (plus SMTP_FROM and AUTH_URL).
Links expire in 30 minutes and are single-use; requesting a new link invalidates the previous one.
Check spam; confirm AUTH_URL matches the public HTTPS origin.

Can't sign out

Use the settings (gear) menu → Sign out.

Production health degraded for auth

GET /api/health should show auth.productionReady: true.
Need: strong AUTH_SECRET, AUTH_URL, AUTH_TRUST_HOST=true, and at least one of SMTP / Google / Microsoft.

HTTPS / browser SSL internal error

Confirm the hostname’s A record is the VPS IP (dig +short your.domain).
Let’s Encrypt only works after public DNS exists. If certs were requested too early, restart the reverse proxy (e.g. systemctl restart caddy) and try again.
App can be healthy on localhost:3000 while HTTPS still fails until ACME succeeds.

Docker: migrate fails with “datasource.url property is required”

Image must include prisma.config.ts (Prisma 7). Rebuild from a current Dockerfile.
Runtime must set DATABASE_URL (compose usually injects it from POSTGRES_PASSWORD).

Docker build: AUTH_SECRET required in production

Current Dockerfiles set a build-only placeholder. Pull/rebuild latest; runtime .env must still set a real AUTH_SECRET.

SSH Permission denied (publickey) on a new VPS

An SSH key listed in the cloud console is not always installed on the VM. Add the public key to /root/.ssh/authorized_keys (rescue mode / console) or recreate the server with the key selected.

Database / Connection Issues

"Error: P1001: Can't reach database server"

Postgres is not running or the host/port in DATABASE_URL is wrong.
With Docker Compose: make sure db service is healthy (docker compose ps, docker compose logs db).
Common fix: use the service name db from inside the app container, or localhost when connecting from the host.

Seed fails or unique constraint errors

Often means partial data already exists.
Do not reset or seed a real installation: both operations can delete data. Investigate the actual constraint error and migration state first. Only for an explicitly disposable development database, npx prisma migrate reset can rebuild it and npx prisma db seed can add samples; neither is an install or update step.

Prisma client out of date after schema change

Run npx prisma generate.

Chat / AI Not Working

Chat responds with text but never creates entries or proposals

No LLM key configured, or wrong provider/model.
Check .env: NEXT_LLM_PROVIDER, NEXT_LLM_MODEL, and the corresponding *_API_KEY.
Test by asking a simple non-action question first ("What is 2+2?").
Look at server logs for the chat route.

AI refuses to create entries for foreign currency

Strict FX rules: it needs a rate + source.
For new foreign amounts it usually needs to search for a provisional rate (LLM_PROVISIONAL).
If it says it cannot find a rate, provide more context or use web_search capable model.
When a statement arrives later, ask for an adjustment entry only.

Everything becomes proposals even when unlocked

Chat lock may be on (check the lock icon).
Or the action is destructive / master-data (always proposals).
Or validation failed (unbalanced journal, unknown account code, etc.).

Git Model / View Confusion

"I don't see my latest entries" or numbers look wrong

You are likely viewing a branch or a past asOf point.
Look at the persistent Books View Indicator at the top.
Click it or use Git controls to return to main (current).

Restore "did nothing" or I lost work

Restore always creates a new ROLLBACK commit on the target branch.
After restore the URL is updated to the new head (no asOf).
Your old work still exists in history - use the commit list or blame to find it.

Chat or panels ignore my branch

All major panels read ?branch and ?asOf from the URL.
Make sure you are on the correct URL or use the branch selector in History view.
Chat always receives the current view from the app.

Backup & Restore

Restore fails with encryption key error

The backup was created with a different ENCRYPTION_KEY.
You must use the exact same key on the target instance for encrypted data (bank credentials, etc.).
See entrytwo_v1/docs/ENCRYPTION-KEY-ROTATION.md.

".etbackup file is too large" or import times out

Large backups can take a long time.
The system has configurable limits (BACKUP_MAX_* env vars).
For very large instances, consider pg_dump + manual file asset copy as a fallback (advanced).

Updates

"No update available" or update disabled

UPDATE_MANIFEST_URL is not set, or the manifest is empty / unreachable.
Signature verification is failing (check Cosign settings and logs).
You are on a licensed instance after trial but without active maintenance (expected behavior).

Update applied but then rolled back

Health check after migration failed.
Check the update logs and the pre-update backup that was created automatically.
You can manually restore the backup if needed.

Licensing / Trial

Trial paywall appears too early or too late

The 30-day clock starts on first use inside the instance (firstUseAt in settings), not download time.
Check the stored license.firstUseAt if you have direct DB access for debugging.

License key "invalid" after purchase

Make sure you are pasting the full et1.... key.
The key is verified once at activation; after that only the stored flag is used ("verify once, trust forever").
Contact support with the key and instance details if activation fails repeatedly.

Performance / General

Slow ledger or reports

Large history with no indexes or no read replica.
Try narrowing date ranges or using the asOf view for historical reporting.
Consider read replicas for heavy reporting workloads.

Attachments not showing or 404

Check that the uploads volume is mounted correctly in Docker.
Verify file permissions inside the container.

Where to Get More Help

Ask the in-app chat with the current view - it has live context + these docs.
Load this documentation set into another model and describe your exact symptoms + what you see in the Books View Indicator.
Check server logs (docker compose logs app or your process manager).
For self-hosted update or licensing issues, include the exact version and manifest status from Admin → Update.

When reporting issues, include:

What you were trying to do
Current view (branch + asOf or "on main current")
Any error messages (exact text)
Whether chat lock was on or off
Recent actions (upload, reconcile, restore, etc.)

This makes it much faster for a human or AI to help.