{"record":{"id":"7aa25915774bfcee","repo":"usebruno/bruno","slug":"failed-to-open-the-database","errorCode":null,"errorMessage":"Failed to open the database.","messagePattern":"Failed to open the database\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/bruno-sqlite/src/node/index.ts","lineNumber":25,"sourceCode":"export { DB } from './db';\nexport type { DatabaseOptions } from './db';\nexport { Statements } from './statements';\nexport type { OnMutation } from './statements';\nexport { registerSQLiteIpc } from './ipc';\nexport type { IpcMainLike } from './ipc';\nexport * from '../shared';\n\nexport const version = '0.1.0';\n\nexport type CreateDatabaseOptions = DatabaseOptions & {\n  onMutation?: OnMutation;\n};\n\nexport const createDatabase = (path: string, options: CreateDatabaseOptions = {}) => {\n  const { onMutation, ...dbOptions } = options;\n  const db = new DB(path, migrations, dbOptions);\n  if (db._db === undefined) {\n    throw new Error('Failed to open the database.');\n  }\n  const statements = new Statements(db._db, onMutation);\n  return { db, statements };\n};\n","sourceCodeStart":7,"sourceCodeEnd":30,"githubUrl":"https://github.com/usebruno/bruno/blob/9bdd81c7bdc57006e5f5ebffb79321a8d979f712/packages/bruno-sqlite/src/node/index.ts#L7-L30","documentation":"Thrown by createDatabase as a defensive guard after constructing DB(path, migrations, dbOptions): if db._db is undefined, the underlying node:sqlite DatabaseSync handle is unusable. The DB constructor sets _db = new DatabaseSync(path, options) and, on migration failure, closes it and sets _db = undefined before re-throwing the migration error; the only way to reach this guard with _db undefined (and no prior throw) is when DatabaseSync itself fails to yield a usable handle — most often because node:sqlite is unavailable in the running Node build or the file path is inaccessible.","triggerScenarios":"createDatabase is invoked with a path on a read-only or non-existent directory, a path the process lacks permission to create/write, or under a Node.js build/version where node:sqlite is not compiled in or is disabled. It can also surface if DatabaseSync throws in a way that the constructor swallows, leaving _db unset without re-throwing.","commonSituations":"Running on Node < 22.5 (or a distro build without experimental sqlite compiled in) where node:sqlite is absent; forgot --experimental-sqlite on a Node version where it is still flagged; data directory does not exist or is read-only (snap/appimage/sandbox); file path is a relative path resolved against an unexpected cwd; disk full or quota exceeded at open time.","solutions":["Run on Node 22.5+ and, where node:sqlite is still experimental, launch with --experimental-sqlite (or set the equivalent flag in your process launcher).","Verify the data directory exists and is writable by the process before calling createDatabase (fs.mkdirSync(dir, { recursive: true }) and an fs.accessSync write check).","Pass an absolute path for the database file to avoid cwd-resolution surprises.","Check available disk space and filesystem quotas if the handle fails to initialize."],"exampleFix":"// before\nconst { db, statements } = createDatabase('./data.db');\n\n// after\nconst path = require('path');\nconst fs = require('fs');\nconst dir = path.resolve(process.env.BRUNO_DATA_DIR || './data');\nfs.mkdirSync(dir, { recursive: true });\nfs.accessSync(dir, fs.constants.W_OK);\nconst { db, statements } = createDatabase(path.join(dir, 'app.db'));","handlingStrategy":"validation","validationCode":"const fs = require('fs');\nconst path = require('path');\nfunction preflightDbPath(p) {\n  const dir = path.dirname(path.resolve(p));\n  fs.mkdirSync(dir, { recursive: true });\n  fs.accessSync(dir, fs.constants.W_OK | fs.constants.R_OK);\n  // node:sqlite availability\n  try { require('node:sqlite'); } catch { throw new Error('node:sqlite unavailable — use Node 22.5+ with --experimental-sqlite if required'); }\n}\npreflightDbPath(dbPath);\nconst { db, statements } = createDatabase(dbPath, options);","typeGuard":null,"tryCatchPattern":"try {\n  return createDatabase(dbPath, options);\n} catch (e) {\n  if (/Failed to open the database\\./.test(e?.message)) {\n    throw new Error(`Could not open SQLite at '${dbPath}'. Check Node ${process.version} supports node:sqlite, the directory is writable, and disk has space.`);\n  }\n  throw e;\n}","preventionTips":["Pin Node 22.5+ and document the --experimental-sqlite flag where applicable.","Always pass an absolute path located in a known-writable app data directory.","Create and write-check the data directory at app startup, before opening the DB.","Surface process.version and the resolved path in the error context for fast triage."],"tags":["database","sqlite","node","initialization","filesystem"],"backgroundTag":null,"analyzedSha":"9bdd81c7bdc57006e5f5ebffb79321a8d979f712","analyzedAt":"2026-08-13T04:09:25.751Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}