Troubleshoot the system
Audience
Section titled “Audience”Framework administrators and deployment operators.
Prerequisites
Section titled “Prerequisites”Access to application status, logs, host storage, and Docker commands when applicable.
App does not start
Section titled “App does not start”Check ports, free disk space, runtime versions, and logs. Windows users can run status.cmd; Docker users can run docker compose ps and docker compose logs --tail=200.
Update check fails
Section titled “Update check fails”Confirm access to GitHub Releases and GHCR. A proxy, DNS rule, API rate limit, missing updater token, or private package visibility can block the request.
Database errors
Section titled “Database errors”Stop writes, preserve the database and WAL files, and create a filesystem copy before attempting recovery. Never edit a production SQLite file directly.