entrytwo
buy

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.
  • Safe reset (development only): npx prisma migrate reset then npm run db:seed.

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

  1. Ask the in-app chat with the current view - it has live context + these docs.
  2. Load this documentation set into another model and describe your exact symptoms + what you see in the Books View Indicator.
  3. Check server logs (docker compose logs app or your process manager).
  4. 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.