What causes "Failed to apply SQLite pragma ${name}" in thedotmack/claude-mem?

Move the DB onto a local writable disk — WAL fundamentally requires it

Failed to apply SQLite pragma ${name}

Error message

Failed to apply SQLite pragma ${name}

What it means

applySqliteConnectionPragmas() runs required pragmas (journal_mode=WAL, incremental auto_vacuum, etc.) on every new SQLite connection. runRequiredPragma() logs the pragma name and SQL, then rethrows — connection setup aborts and the caller gets the original SQLite error.

Source

Thrown at src/services/sqlite/connection.ts:30

}

function hasUserTables(db: Database): boolean {
  const row = db.prepare(`
    SELECT name
    FROM sqlite_master
    WHERE type = 'table'
      AND name NOT LIKE 'sqlite_%'
    LIMIT 1
  `).get() as { name: string } | undefined;
  return row != null;
}

function runRequiredPragma(db: Database, sql: string, name: string): void {
  try {
    db.run(sql);
  } catch (error) {
    const err = error instanceof Error ? error : new Error(String(error));
    logger.warn('DB', `Failed to apply SQLite pragma ${name}`, { sql }, err);
    throw error;
  }
}

export function applySqliteConnectionPragmas(
  db: Database,
  options: SqlitePragmaOptions = {},
): void {
  const {
    enableWal = true,
    enableIncrementalAutoVacuum = true,
  } = options;

  runRequiredPragma(db, `PRAGMA busy_timeout = ${SQLITE_BUSY_TIMEOUT_MS}`, 'busy_timeout');
  runRequiredPragma(db, 'PRAGMA foreign_keys = ON', 'foreign_keys');
  runRequiredPragma(db, 'PRAGMA synchronous = NORMAL', 'synchronous');
  runRequiredPragma(db, `PRAGMA journal_size_limit = ${SQLITE_JOURNAL_SIZE_LIMIT_BYTES}`, 'journal_size_limit');

View on GitHub (pinned to e2d1df569a)

Solutions

Move the DB onto a local writable disk — WAL fundamentally requires it
Fix permissions on the DB file and its directory (WAL creates -wal/-shm files alongside)
Close any other process holding the DB before restarting
Check the logged sql field to see exactly which pragma failed and reproduce it in a sqlite shell
If WAL truly cannot be used, pass enableWal: false via SqlitePragmaOptions where the connection is created

Defensive patterns

Strategy: validation

Validate before calling

import { accessSync, constants } from 'node:fs';
import { dirname } from 'node:path';

function assertDbWritable(dbPath: string): void {
  accessSync(dirname(dbPath), constants.W_OK); // -wal/-shm siblings are created here
  try {
    accessSync(dbPath, constants.W_OK);
  } catch {
    // creating a new file is fine; an existing unwritable one is not
  }
}

Try / catch

try {
  applySqliteConnectionPragmas(db, { enableWal: true });
} catch (err) {
  // fail fast with a configuration error naming the DB path;
  // never proceed with a half-configured connection
  throw new Error(`SQLite connection setup failed for ${dbPath}: ${String(err)}`);
}

Prevention

Never place SQLite WAL databases on network or cloud-synced filesystems
Grant write access to the whole DB directory, not just the file
Open each DB from one process at a time to avoid exclusive-lock pragma failures

When it happens

Trigger: PRAGMA journal_mode=WAL on a read-only database or a filesystem without WAL shared-memory support (SMB/NFS); setting auto_vacuum while the DB is inside a transaction; permission errors creating the -wal/-shm sibling files.

Common situations: DB file moved onto a network share or cloud-synced folder (Dropbox/OneDrive); file ownership/permissions changed (EACCES/EROFS); a container or VM opening the file without write permission; another process holding an exclusive lock.

Related errors

AI-assisted analysis of thedotmack/claude-mem@e2d1df569a (2026-08-20). Data as JSON: /api/errors/bde1233d939a9bd4. Report an issue: GitHub.