{"record":{"id":"89327ad09836857f","repo":"tobi/qmd","slug":"sqlite-vec-extension-is-unavailable-hint","errorCode":null,"errorMessage":"sqlite-vec extension is unavailable. ${hint}","messagePattern":"sqlite-vec extension is unavailable\\. (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"src/db.ts","lineNumber":158,"sourceCode":"  run(...params: SQLiteValue[]): { changes: number; lastInsertRowid: number | bigint };\n  get<T = unknown>(...params: SQLiteValue[]): T | undefined;\n  all<T = unknown>(...params: SQLiteValue[]): T[];\n  iterate<T = unknown>(...params: SQLiteValue[]): IterableIterator<T>;\n}\n\n/**\n * Load the sqlite-vec extension into a database.\n *\n * Throws with platform-specific fix instructions when the extension is\n * unavailable.\n */\nexport function loadSqliteVec(db: Database): void {\n  if (!_sqliteVecLoad) {\n    const hint = isBun && process.platform === \"darwin\"\n      ? \"On macOS with Bun, install Homebrew SQLite: brew install sqlite\\n\" +\n        \"Or install qmd with npm instead: npm install -g @tobilu/qmd\"\n      : \"Ensure the sqlite-vec native module is installed correctly.\";\n    throw new Error(`sqlite-vec extension is unavailable. ${hint}`);\n  }\n  _sqliteVecLoad(db);\n}\n","sourceCodeStart":140,"sourceCodeEnd":162,"githubUrl":"https://github.com/tobi/qmd/blob/dbfd0b4736aeaf761d1a16ca8e424f071df8feb9/src/db.ts#L140-L162","documentation":"The sqlite-vec native extension could not be loaded, so vector search (embeddings) is unavailable. The qmd binary ships a loader for sqlite-vec; if the native module was not bundled or the runtime's SQLite can't load extensions, _sqliteVecLoad is null and this error is thrown with a platform-specific hint (notably Bun on macOS).","triggerScenarios":"Initializing the database (initializeDatabase / initTestDatabase / createStore) when running under Bun on macOS without Homebrew SQLite, or with a broken/partial install where the .dylib loader is missing.","commonSituations":"Running qmd via bun on macOS where Bun's bundled SQLite lacks extension loading; installing with npm on a platform without prebuilt sqlite-vec binaries; upgrading Bun or qmd versions that break native module loading.","solutions":["On macOS with Bun: brew install sqlite (per the hint)","Or install via npm instead: npm install -g @tobilu/qmd","Run `qmd doctor` to confirm the extension and device status","Reinstall qmd to restore the native module"],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"// Detect Bun+macOS risk before startup\nconst risky = typeof Bun !== 'undefined' && process.platform === 'darwin';\nif (risky) console.error('Install Homebrew SQLite first: brew install sqlite');","typeGuard":null,"tryCatchPattern":"try {\n  const store = await createStore({ dbPath, configPath });\n} catch (e) {\n  if (e instanceof Error && e.message.includes('sqlite-vec')) {\n    // fall back to BM25-only search, advise npm install / brew install sqlite\n  } else throw e;\n}","preventionTips":["Prefer the npm-installed qmd binary on macOS","Run `qmd doctor` after installs/upgrades","brew install sqlite before using Bun on macOS"],"tags":["sqlite","native-module","sqlite-vec","bun","macos"],"backgroundTag":"native-extension-load-failure","analyzedSha":"dbfd0b4736aeaf761d1a16ca8e424f071df8feb9","analyzedAt":"2026-08-28T18:07:46.628Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}