Troubleshooting

Database Issues

”database is locked” (SQLite)

This typically happens when multiple processes attempt to write to the SQLite database simultaneously, or a long-running transaction is holding a lock.

Solution: We use WAL (Write-Ahead Logging) mode to minimize this. Ensure your local environment also has WAL enabled.
Check: Run mise run backend:check which includes a PRAGMA verification test.

Missing Migrations

If you see errors related to missing columns or tables after a pull:

Solution: Run the migration script:
Terminal window
```
cd backend-api/
uv run alembic upgrade head
```

Docker & Deployment

Build Context Failures (.npmrc not found)

If the Docker build fails with "/frontend-pwa/.npmrc": not found:

Cause: The .npmrc file is ignored in .dockerignore but the Dockerfile attempts to COPY it.
Solution: Ensure your Dockerfile generates the .npmrc dynamically inside the RUN command rather than copying it from the host.

ARM64 Cross-Compilation OOM

Building for Raspberry Pi (ARM64) on a local machine with limited resources can sometimes max out memory.

Solution: Use GitHub-hosted runners for production builds (as configured in our deploy workflows). Locally, ensure Docker Desktop has at least 4GB of RAM allocated.

Frontend & PWA

Changes Not Appearing (Caching)

Since the app is a Progressive Web App, the Service Worker might be serving a cached version.

Solution:
- Force refresh (Cmd+Shift+R or Ctrl+F5).
- Or, go to DevTools > Application > Service Workers and click Update on reload or Unregister.

”Mock Auth” Not Working

Check: Ensure VITE_MOCK_AUTH=true is in frontend-pwa/.env.local AND MOCK_AUTH=true is in backend-api/.env. Both must be synchronized.

Operational Scripts

`refresh_local_db.sh` Unauthorized

Cause: The script uses the GitHub CLI (gh) to fetch production backups.
Solution: Ensure you are logged in and have the necessary permissions:
Terminal window
```
gh auth login
```