tobi/qmd · critical · Error

sqlite-vec extension is unavailable. ${hint}

Error message

sqlite-vec extension is unavailable. ${hint}

What it means

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).

Source

Thrown at src/db.ts:158

  run(...params: SQLiteValue[]): { changes: number; lastInsertRowid: number | bigint };
  get<T = unknown>(...params: SQLiteValue[]): T | undefined;
  all<T = unknown>(...params: SQLiteValue[]): T[];
  iterate<T = unknown>(...params: SQLiteValue[]): IterableIterator<T>;
}

/**
 * Load the sqlite-vec extension into a database.
 *
 * Throws with platform-specific fix instructions when the extension is
 * unavailable.
 */
export function loadSqliteVec(db: Database): void {
  if (!_sqliteVecLoad) {
    const hint = isBun && process.platform === "darwin"
      ? "On macOS with Bun, install Homebrew SQLite: brew install sqlite\n" +
        "Or install qmd with npm instead: npm install -g @tobilu/qmd"
      : "Ensure the sqlite-vec native module is installed correctly.";
    throw new Error(`sqlite-vec extension is unavailable. ${hint}`);
  }
  _sqliteVecLoad(db);
}

View on GitHub (pinned to dbfd0b4736)

Solutions

1. On macOS with Bun: brew install sqlite (per the hint)
2. Or install via npm instead: npm install -g @tobilu/qmd
3. Run `qmd doctor` to confirm the extension and device status
4. Reinstall qmd to restore the native module

// Detect Bun+macOS risk before startup
const risky = typeof Bun !== 'undefined' && process.platform === 'darwin';
if (risky) console.error('Install Homebrew SQLite first: brew install sqlite');

try {
  const store = await createStore({ dbPath, configPath });
} catch (e) {
  if (e instanceof Error && e.message.includes('sqlite-vec')) {
    // fall back to BM25-only search, advise npm install / brew install sqlite
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Embedding dimension mismatch: existing vectors are ${existin

AI-assisted analysis of tobi/qmd@dbfd0b4736 (2026-08-28). Data as JSON: /api/errors/89327ad09836857f. Report an issue: GitHub.