tinyhumansai/openhuman · error

stale SQLite side-file present (may indicate unclean shutdow

Error message

stale SQLite side-file present (may indicate unclean shutdown): {}

What it means

Doctor memory-tree check: a chunks.db-shm or chunks.db-wal sidecar exists next to the SQLite database. SQLite deletes these on clean shutdown; a surviving -shm/-wal pair means the last process died without closing the DB (crash, kill -9, power loss). The data is normally recovered by WAL replay on next open, but the flag warns that unclean shutdown occurred and, if a stale process still holds the file, locking issues are possible.

Source

Thrown at src/openhuman/platform/doctor/core.rs:805

/// - If the DB directory / file does not exist yet: `Warn` (not yet created).
/// - If a stale `.db-shm` file is present alongside the DB: `Warn`.
/// - If we can open the DB and run a basic probe query: `Ok`.
/// - If the probe fails: `Error`.
fn check_memory_tree_db(config: &Config, items: &mut Vec<DiagnosticItem>) {
    let cat = "memory_tree_db";
    let db_path = config.workspace_dir.join("memory_tree").join("chunks.db");

    // ── Stale side-files (checked even when chunks.db is absent) ────
    let base_name = db_path
        .file_name()
        .unwrap_or_default()
        .to_string_lossy()
        .into_owned();
    let shm = db_path.with_file_name(format!("{base_name}-shm"));
    let wal = db_path.with_file_name(format!("{base_name}-wal"));
    for sidecar in [&shm, &wal] {
        if sidecar.exists() {
            items.push(DiagnosticItem::warn(
                cat,
                format!(
                    "stale SQLite side-file present (may indicate unclean shutdown): {}",
                    sidecar.display()
                ),
            ));
        }
    }

    // ── File existence ──────────────────────────────────────────────
    if !db_path.exists() {
        items.push(DiagnosticItem::warn(
            cat,
            format!(
                "DB not yet created (first ingest will initialise it): {}",
                db_path.display()
            ),
        ));

View on GitHub (pinned to 7491200858)

Solutions

1. Open the core once so SQLite replays the WAL and removes the sidecars cleanly
2. If sidecars persist after a clean shutdown, no process may be holding the DB — stop all core instances and delete the -shm/-wal pair only after backing up chunks.db
3. Investigate the cause of the unclean shutdown (OOM killer, forced quit) to avoid WAL corruption

When it happens

Trigger: Thrown at src/openhuman/platform/doctor/core.rs:805 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of tinyhumansai/openhuman@7491200858 (2026-08-17). Data as JSON: /api/errors/e4482f6e749417b8. Report an issue: GitHub.