remix-run/remix · error · Error

SQLite config-based construction requires node:sqlite (Node.

Error message

SQLite config-based construction requires node:sqlite (Node.js 22.5+) or bun:sqlite; pass a SQLite database client instead

What it means

For config-based construction the SQLite driver dynamically imports node:sqlite (Node 22.5+) or bun:sqlite to get DatabaseSync. If neither module exists in the runtime, this error tells you to either upgrade the runtime or pass an already-open database client.

Source

Thrown at packages/data-table-sqlite/src/lib/driver.ts:70

// and so bundlers never try to resolve those specifiers statically.
function loadSqliteDatabaseConstructor(): SqliteDatabaseConstructor {
  if (!loadedDriverConstructor) {
    if ('Bun' in globalThis) {
      // import.meta.require is Bun's synchronous require for ES modules; Bun does not
      // implement process.getBuiltinModule
      let importMeta = import.meta as ImportMeta & { require?: (id: string) => unknown }
      let driver = importMeta.require?.('bun:sqlite') as SqliteDriverModule | undefined
      loadedDriverConstructor = driver?.Database
    } else {
      // process.getBuiltinModule loads node:sqlite synchronously (Node.js 22.3+)
      let driver = globalThis.process?.getBuiltinModule?.('node:sqlite') as
        | SqliteDriverModule
        | undefined
      loadedDriverConstructor = driver?.DatabaseSync
    }

    if (!loadedDriverConstructor) {
      throw new Error(
        'SQLite config-based construction requires node:sqlite (Node.js 22.5+) or bun:sqlite; pass a SQLite database client instead',
      )
    }
  }

  return loadedDriverConstructor
}

/** Configuration for a SQLite database created by `createSqliteDatabase()`. */
export interface SqliteDatabaseConfig {
  /** SQLite database filename or `:memory:` for an in-memory database. */
  filename: string
  /**
   * Enables SQLite foreign key enforcement whenever the database opens a connection.
   * Defaults to `false` (enforcement off) on every runtime, including Node.js where
   * `node:sqlite` would otherwise enable it by default.
   */
  foreignKeys?: boolean

View on GitHub (pinned to 9696913134)

Solutions

1. Upgrade to Node 22.5+ (or run under Bun) so node:sqlite is available
2. Otherwise construct the driver with an existing client: new SqliteDatabase(client) using node:sqlite's DatabaseSync, better-sqlite3, or bun:sqlite
3. Pin/verify the runtime version in CI to match the SQLite requirements

Example fix

// before
new SqliteDatabase({ filename: './app.db' }) // throws on Node 20

// after
import { DatabaseSync } from 'node:sqlite' // Node 22.5+
new SqliteDatabase(new DatabaseSync('./app.db'))

import { isSqliteRuntimeSupported } from './runtime-check' // or check manually
const major = parseInt(process.versions.node.split('.')[0], 10)
const minor = parseInt(process.versions.node.split('.')[1] ?? '0', 10)
const supported = process.versions.bun || (major === 22 && minor >= 5) || major > 22

function supportsNodeSqlite(): boolean {
  if (process.versions.bun) return true
  const [maj, min] = process.versions.node.split('.').map(Number)
  return maj > 22 || (maj === 22 && min >= 5)
}

When it happens

Trigger: Running on Node < 22.5 (e.g. Node 18/20/22.0) or a non-Bun runtime and constructing the SQLite driver with a config object (filename/options) instead of a client instance; bundlers stripping the dynamic imports.

Common situations: Deploying to LTS Node images older than 22.5; running tests under Node 20 while developing under Bun; serverless runtimes without node:sqlite.

Related errors

• SQLite database + method + () requires config-based constru
• SQLite database cannot ' + method + ' while transactions are
• Unknown transaction token: ' + token.id
• expected error to be ${describeExpectedError(args[0])}, got
• MySQL database + method + () requires config-based construc

AI-assisted analysis of remix-run/remix@9696913134 (2026-08-27). Data as JSON: /api/errors/4180368f736d43db. Report an issue: GitHub.