What causes "[DB] better-sqlite3 unavailable: ${e.message}" in decolua/9router?

Run npm install (or npm rebuild better-sqlite3) to rebuild the native module for the current Node version.

[DB] better-sqlite3 unavailable: ${e.message}

Error message

[DB] better-sqlite3 unavailable: ${e.message}

What it means

Second link in the driver fallback chain. tryBetterSqlite attempts to load the optional native better-sqlite3 dependency; on any import or init failure (it is skipped entirely under Bun), it logs this warning and returns null so the chain continues with node:sqlite. Because better-sqlite3 is only in optionalDependencies, failure is expected on machines without native build tools.

Source

Thrown at src/lib/db/driver.js:26

  // Bun runtime only — built-in, no install needed
  if (!process.versions.bun) return null;
  try {
    const { createBunSqliteAdapter } = await import("./adapters/bunSqliteAdapter.js");
    return await createBunSqliteAdapter(DATA_FILE);
  } catch (e) {
    console.warn(`[DB] bun:sqlite unavailable: ${e.message}`);
    return null;
  }
}

async function tryBetterSqlite() {
  // Skip on Bun — better-sqlite3 native bindings unsupported
  if (process.versions.bun) return null;
  try {
    const { createBetterSqliteAdapter } = await import("./adapters/betterSqliteAdapter.js");
    return createBetterSqliteAdapter(DATA_FILE);
  } catch (e) {
    console.warn(`[DB] better-sqlite3 unavailable: ${e.message}`);
    return null;
  }
}

async function tryNodeSqlite() {
  // Built-in since Node 22.5.0 — no install needed. Skip under Bun (no node:sqlite).
  if (process.versions.bun) return null;
  const [maj, min] = process.versions.node.split(".").map(Number);
  if (maj < 22 || (maj === 22 && min < 5)) return null;
  try {
    const { createNodeSqliteAdapter } = await import("./adapters/nodeSqliteAdapter.js");
    return await createNodeSqliteAdapter(DATA_FILE);
  } catch (e) {
    console.warn(`[DB] node:sqlite unavailable: ${e.message}`);
    return null;
  }
}

View on GitHub (pinned to 90b52e06ff)

Solutions

Run npm install (or npm rebuild better-sqlite3) to rebuild the native module for the current Node version.
Install build prerequisites (python3, make, g++) if the install log showed a build failure.
Rely on the fallback: Node >= 22.5 uses built-in node:sqlite — nothing to fix.
Ensure DATA_FILE's directory is writable and the file isn't corrupt/locked.

Example fix

// before
Node upgraded 20 -> 22, better-sqlite3 binding stale
// after
npm rebuild better-sqlite3   # or: npm install

Defensive patterns

Strategy: fallback

Validate before calling

try { await import("better-sqlite3"); console.log("better-sqlite3 OK"); }
catch (e) { console.warn("better-sqlite3 missing/mismatched — run npm rebuild better-sqlite3"); }

Prevention

After any Node version change, run npm rebuild better-sqlite3 to match the new ABI.
Don't install with --omit=optional if you want the native driver.
Provide build tools (python3, make, g++) in CI/container images.
Log adapter.driver at startup to detect silent fallback to node:sqlite/sql.js.

When it happens

Trigger: Node runtime where better-sqlite3 is not installed (skipped optional dep), its native binding was built for a different Node ABI (NODE_MODULE_VERSION mismatch after a Node upgrade), the build failed during npm install (missing node-gyp/python/compilers), or createBetterSqliteAdapter cannot open DATA_FILE.

Common situations: Upgrading Node versions without reinstalling; npm install --omit=optional; Alpine/scratch containers lacking build toolchain; Electron/Node ABI mismatch.

Related errors

AI-assisted analysis of decolua/9router@90b52e06ff (2026-08-30). Data as JSON: /api/errors/ca4c5874ebd3d5ed. Report an issue: GitHub.