[backend: ] SQLite store is corrupt and will be rebuilt: …

Error message

[backend:${ownerId}] SQLite store is corrupt and will be rebuilt: ${dbFile}. Corrupt copy saved to ${backupFile}. Error: ${formatError(error)}

What it means

Opening the backend's SQLite store failed in a way that indicates corruption. The service copies the corrupt database to a backup path, deletes the database files, logs the corruption cause, and recreates a fresh database. Data in the old store is lost from the service's perspective (only recoverable from the backup copy).

Solutions

Restore from the saved backup copy if the data matters: inspect <backupFile> with the sqlite3 CLI (PRAGMA integrity_check) and recover rows before it gets overwritten
Ensure clean shutdowns (SIGTERM handling) so WAL checkpoints complete
Check disk health and free space — recurring corruption usually means failing storage or crashes mid-write
Consider periodic backups of the backend DB

Example fix

# inspect and salvage the backup
sqlite3 /path/to/corrupt-backup.db "PRAGMA integrity_check;"
sqlite3 /path/to/corrupt-backup.db .dump | sqlite3 recovered.db
# then point config at recovered.db or restore it to the original dbFile path

Defensive patterns

Strategy: fallback

Validate before calling

const ok = db.pragma("quick_check", { simple: true }) === "ok";
if (!ok) throw new Error("SQLite store failing integrity check — back it up now");

Try / catch

try { openDb(); } catch (e) { /* copy db aside, then rebuild from backup — never delete the corrupt copy */ }

Prevention

Handle SIGTERM so the process checkpoints SQLite cleanly
Keep the backend DB on reliable storage with free space
Schedule periodic backups of the backend DB
Never copy DB files while the process is running

When it happens

Trigger: better-sqlite3 throwing SQLITE_CORRUPT or a pragma integrity failure on open; truncated database file from a crash mid-write; power loss or killed process during a transaction; incompatible SQLite page corruption.

Common situations: Hard-killing the gateway process during heavy writes; disk full during commit; moving/copying DB files while running; FS corruption. Recurrence means an underlying storage or shutdown-hygiene problem.

Related errors

AI-assisted analysis of musistudio/claude-code-router@99f24806c6 (2026-08-27). Data as JSON: /api/errors/ba35019d55c25a22. Report an issue: GitHub.

Appendix: source

Thrown at packages/core/src/plugins/backend-service.ts:176

export const backendService = new BackendService();

function openSqliteDatabaseWithRecovery(ownerId: string, dbFile: string): SqlDatabase {
  try {
    const database = openBetterSqliteDatabase(dbFile);
    assertSqliteDatabaseIntegrity(database);
    return database;
  } catch (error) {
    if (!isSqliteOpenCorruptionError(error)) {
      throw error;
    }

    const backupFile = nextCorruptSqliteBackupPath(dbFile);
    if (existsSync(dbFile)) {
      copyFileSync(dbFile, backupFile);
    }
    removeSqliteDatabaseFiles(dbFile);
    console.warn(
      `[backend:${ownerId}] SQLite store is corrupt and will be rebuilt: ${dbFile}. ` +
      `Corrupt copy saved to ${backupFile}. Error: ${formatError(error)}`
    );
    return openBetterSqliteDatabase(dbFile);
  }
}

function openBetterSqliteDatabase(dbFile: string): SqlDatabase {
  const raw = createBetterSqliteDatabase(dbFile);
  raw.pragma("journal_mode = WAL");
  raw.pragma("synchronous = NORMAL");
  raw.pragma("busy_timeout = 5000");
  return new SqliteCompatDatabase(raw);
}

class SqliteCompatDatabase implements SqlDatabase {
  constructor(private readonly raw: BetterSqliteDatabase) {}

View on GitHub (pinned to 99f24806c6)