Console store recovery¶
This procedure is for the person operating the Console server. For a disconnected browser or an interrupted calculation, start with recover a run.
Use this procedure when your supplied runtime includes Console and reports that its workspace store is unavailable. It preserves the current state while you check a compatible build or a backup in isolation. It does not repair an engineering run bundle or resume a solver.
Identify the failure¶
Read the warning in the terminal that started Console. On startup it distinguishes an unsupported newer schema, an integrity check failure, an unavailable pre-migration backup, an incomplete upgrade, or an unreadable workspace. The browser and HTTP API withhold private paths and database details.
| Terminal finding | Next action |
|---|---|
| Newer Sindri build | Use a build that supports that store. Do not edit its schema version to make an older build accept it. |
| Integrity check failure | Check storage health, preserve the current state, and inspect a backup copy. |
| Backup could not be created or verified | Check free space, permissions and the existing backup. Keep a failed or conflicting backup for inspection. |
| Upgrade did not complete | Check storage capacity, permissions and competing writers before retrying with a compatible build. |
| Workspace could not be read | Check access and competing writers, then inspect the workspace in an isolated copy. A readable SQLite file can still contain invalid workspace records. |
A failure that appears after startup may have only the generic unavailable message. Preserve the state before investigating or restarting. These findings do not justify deleting the database or resetting the workspace.
If the terminal reports post-run review startup unavailable, the workspace may still open, but saved review work could not be reconciled. Reviews stay disabled for that server session. Preserve the state and ask the runtime maintainer to inspect an isolated copy of the review records before restarting a compatible build. Do not use a provider retry to repair a store failure.
Preserve the current state¶
- Stop the Console server and its running workers through their normal controls. Confirm that no other Console process or worker is using this state directory. A server shutdown alone does not prove every worker has exited.
- Locate
sindri/console.sqlite3beneath the server'sXDG_STATE_HOME, or~/.local/state/sindri/console.sqlite3when that variable was unset. Use the environment of the server process, which may differ from your terminal. - Copy the entire
sindristate directory to a private preservation location, retaining permissions and any SQLite-wal,-shmor-journalfiles. Keep it unchanged. State can include credentials, working copies, drafts, labels, history and review records. Keep separately stored project and run directories as well; the control database is not their backup.
Before an upgrade, Console creates a verified SQLite backup named
console.sqlite3.pre-v<old>-to-v<new> beside the database. The numbers identify
the actual schema transition. An existing backup may be from an earlier attempt;
its presence alone does not establish its contents or freshness.
Check and restore a separate copy¶
- Copy the chosen pre-migration backup to a new private trial state directory as
sindri/console.sqlite3. Keep both the original backup and preserved current directory untouched. Do not reuse the current database's journal files with a different backup. - With no writer using that trial copy, open it read-only in SQLite and inspect
PRAGMA quick_checkandPRAGMA user_version.quick_checkshould returnok; the schema must match the backup's recorded version. This checks SQLite integrity, not completeness of authored state or validity of run evidence. - Use a filesystem-isolated environment that can access only trial copies of
the state and referenced project/run locations. Stored absolute paths must
resolve to those copies or be inaccessible; clearing configured roots alone
does not isolate recorded launch paths. Start a compatible installed build
with
XDG_STATE_HOMEset to the trial directory, isolated config/cache directories, a different loopback port and no configured project/run roots. Keep the agent disabled withSINDRI_CONSOLE_AGENT=0. Review the startup warning before opening Console. Recovery checks can inspect recorded locations. Do not press Run or Resume while inspecting a restore. - Verify the workspace, saved drafts and checkpoints, resource bindings, names/tags, comparison links and relevant review history. A successful schema upgrade alone does not prove all user work is available. Restoring an older backup can lose every workspace change made after that backup, including references to newer work that remains elsewhere on disk.
- If the trial is acceptable, stop its server and workers. Deliberately choose the verified trial state as the active state directory for the compatible build. Retain the preserved current state and original backup until you have checked the restored workflow. Do not overwrite the only copy of either.
An invalid backup, an unsupported schema or a failed trial stays unavailable; there is no automatic downgrade or reset. Retain the failure details for the runtime maintainer if no compatible build and verified backup resolve it.
Continue with run inspection and recovery only after confirming the intended workspace and the identity of each saved run.