From 0adbdeb337bb109bf9b131a80452e85670a49b9f Mon Sep 17 00:00:00 2001
From: kuishou68 <54054995+kuishou68@users.noreply.github.com>
Date: Thu, 9 Apr 2026 10:13:40 +0800
Subject: [PATCH] fix(store): surface actionable sqlite-vec guidance

---
 src/store.ts       | 10 ++++++++--
 test/store.test.ts | 14 ++++++++++++++
 2 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/src/store.ts b/src/store.ts
index ab4cbf4..ec5b029 100644
--- a/src/store.ts
+++ b/src/store.ts
@@ -708,6 +708,8 @@ function createSqliteVecUnavailableError(reason: string): Error {
   );
 }
 
+let _sqliteVecUnavailableReason: string | null = null;
+
 function getErrorMessage(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
@@ -731,10 +733,12 @@ function initializeDatabase(db: Database): void {
     loadSqliteVec(db);
     verifySqliteVecLoaded(db);
     _sqliteVecAvailable = true;
+    _sqliteVecUnavailableReason = null;
   } catch (err) {
     // sqlite-vec is optional — vector search won't work but FTS is fine
     _sqliteVecAvailable = false;
-    console.warn(getErrorMessage(err));
+    _sqliteVecUnavailableReason = getErrorMessage(err);
+    console.warn(_sqliteVecUnavailableReason);
   }
   db.exec("PRAGMA journal_mode = WAL");
   db.exec("PRAGMA foreign_keys = ON");
@@ -1049,7 +1053,9 @@ export function isSqliteVecAvailable(): boolean {
 
 function ensureVecTableInternal(db: Database, dimensions: number): void {
   if (!_sqliteVecAvailable) {
-    throw new Error("sqlite-vec is not available. Vector operations require a SQLite build with extension loading support.");
+    throw createSqliteVecUnavailableError(
+      _sqliteVecUnavailableReason ?? "vector operations require a SQLite build with extension loading support"
+    );
   }
   const tableInfo = db.prepare(`SELECT sql FROM sqlite_master WHERE type='table' AND name='vectors_vec'`).get() as { sql: string } | null;
   if (tableInfo) {
diff --git a/test/store.test.ts b/test/store.test.ts
index 47b481b..33bd9fa 100644
--- a/test/store.test.ts
+++ b/test/store.test.ts
@@ -339,6 +339,20 @@ describe("Store Creation", () => {
     }
   });
 
+  test("ensureVecTable surfaces actionable sqlite-vec guidance", async () => {
+    const store = await createTestStore();
+    try {
+      if (typeof process.getBuiltinModule === "function") {
+        expect(() => store.ensureVecTable(768)).not.toThrow();
+      } else {
+        expect(() => store.ensureVecTable(768)).toThrow(/sqlite-vec extension is unavailable/);
+        expect(() => store.ensureVecTable(768)).toThrow(/Install Homebrew SQLite/);
+      }
+    } finally {
+      await cleanupTestDb(store);
+    }
+  });
+
   test("store.close closes the database connection", async () => {
     const store = await createTestStore();
     store.close();