Skip to content

Bundled dylib has unresolved @@HOMEBREW_PREFIX@@ placeholder — extension loading always fails #37

Closed

Description

@Alph4d0g

Summary

The bundled libsqlite3.dylib files in native/darwin-arm64/ and native/darwin-x64/ have an unresolved Homebrew build placeholder as their install name, making them non-functional on every machine. The "bundled dylib" feature introduced in 2.8.8 has never worked — it silently fails and falls back to customSqlitePath or Homebrew auto-detect.

Error

Error: Failed to load sqlite-vec extension: Error: This build of sqlite3 does not support dynamic extension loading

Root Cause

The bundled dylib was copied from Homebrew's build directory rather than the installed location. During brew install --build-from-source, Homebrew uses @@HOMEBREW_PREFIX@@ as a placeholder in the dylib's install name, which gets resolved to the actual prefix (e.g. /opt/homebrew) only during the install step.

$ otool -D native/darwin-arm64/libsqlite3.dylib
@@HOMEBREW_PREFIX@@/opt/sqlite/lib/libsqlite3.dylib

$ otool -L native/darwin-arm64/libsqlite3.dylib
	@@HOMEBREW_PREFIX@@/opt/sqlite/lib/libsqlite3.dylib (compatibility version 9.0.0, current version 9.6.0)
	/usr/lib/libz.1.dylib (compatibility version 1.0.0, current version 1.2.12)
	/usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1345.120.2)

Compare with a properly installed Homebrew SQLite:

$ otool -D /opt/homebrew/opt/sqlite/lib/libsqlite3.dylib
/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib

Affected Files

  • native/darwin-arm64/libsqlite3.dylib (SHA256: 3e411de29265cafbbc0c26fe331ccdd7b023c08f1553badd0584b92f1279fb68)
  • native/darwin-x64/libsqlite3.dylib (likely same issue)

Environment

  • macOS (Apple Silicon, arm64)
  • opencode-mem 2.8.9
  • Homebrew SQLite installed

Activity

  1. Alph4d0g commented on Feb 20, 2026

    @Alph4d0g
    Author

    Update: Deeper Root Cause Found

    The broken @@HOMEBREW_PREFIX@@ placeholder in the bundled dylib is a secondary issue. Even with a correctly built dylib, setCustomSQLite() would never work because OpenCode's embedded Bun runtime compiles SQLite with SQLITE_OMIT_LOAD_EXTENSION, and it initializes before any plugin code runs.

    Evidence

    The OpenCode v1.2.0 binary (opencode-darwin-arm64) embeds Bun with SQLite that has extension loading disabled at compile time:

    $ strings .../opencode-darwin-arm64/bin/opencode | grep "SQLITE_OMIT_LOAD_EXTENSION\|setCustomSQLite"
    SQLITE_OMIT_LOAD_EXTENSION
    setCustomSQLite
    

    What happens at runtime

    1. OpenCode starts → Bun initializes its built-in SQLite (with SQLITE_OMIT_LOAD_EXTENSION)
    2. opencode-mem plugin loads → sqlite-bootstrap.js calls Database.setCustomSQLite(path)
    3. Bun throws "SQLite already loaded" because its SQLite was initialized at startup
    4. trySetCustomSQLite() catches this error and treats it as success (line 100-101)
    5. sqliteVec.load(db) fails because the active SQLite has extension loading permanently disabled

    Why no config workaround helps

    • customSqlitePath → setCustomSQLite() still gets "SQLite already loaded", same result
    • Bundled dylib (even if fixed) → same problem
    • Homebrew auto-detect → same problem

    The setCustomSQLite() call is a no-op regardless of what path is provided, because Bun's internal SQLite is already loaded before any plugin code executes.

    Possible fixes

    1. OpenCode side: Rebuild the embedded Bun without SQLITE_OMIT_LOAD_EXTENSION
    2. opencode-mem side: Use a standalone SQLite binding (e.g., better-sqlite3 with N-API) instead of bun:sqlite, shipping its own SQLite with extension support that isn't affected by Bun's built-in SQLite
    3. opencode-mem side: Use sqlite-vec's pure WASM fallback if available, bypassing native extension loading entirely
  2. Alph4d0g commented on Feb 20, 2026

    @Alph4d0g
    Author

    Update 2: setCustomSQLite is fundamentally broken when running under OpenCode

    Further investigation reveals the problem is not just SQLITE_OMIT_LOAD_EXTENSION — it's that Database.setCustomSQLite() can never succeed when called from a plugin.

    Why setCustomSQLite is a no-op

    setCustomSQLite() only works if called before any Database is instantiated. Once any code calls new Database(...), Bun's internal SQLite is locked in and setCustomSQLite() throws "SQLite already loaded".

    OpenCode (the host application) opens its own SQLite databases during startup — before any plugin code runs. By the time opencode-mem's sqlite-bootstrap.js executes, it's already too late. The bootstrap code catches "SQLite already loaded" and treats it as success (line 100-101), but the active SQLite is still the built-in one without extension support.

    Verified with standalone Bun

    // This WORKS — setCustomSQLite before any Database:
    const { Database } = require("bun:sqlite");
    Database.setCustomSQLite("/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib");
    const db = new Database(":memory:");
    db.loadExtension("path/to/vec0.dylib"); // SUCCESS
    
    // This FAILS — simulating what happens under OpenCode:
    const { Database } = require("bun:sqlite");
    const earlyDb = new Database(":memory:"); // OpenCode does this at startup
    earlyDb.close();
    Database.setCustomSQLite("/opt/homebrew/opt/sqlite/lib/libsqlite3.dylib"); // throws "SQLite already loaded"
    const db = new Database(":memory:");
    db.loadExtension("path/to/vec0.dylib"); // FAILS — extension loading disabled

    What we tried that doesn't work

    Approach Result
    customSqlitePath config setCustomSQLite silently fails (SQLite already loaded)
    Bundled dylib (Priority 1) Same — too late
    Homebrew auto-detect (Priority 3) Same — too late
    DYLD_INSERT_LIBRARIES preload Bun's SQLite is statically linked, can't override
    bunfig.toml with preload Compiled Bun binaries don't read bunfig.toml
    --preload flag Compiled binary ignores Bun runtime flags
    BUN_PRELOAD env var Not respected by compiled binaries

    The only path forward

    The setCustomSQLite + bun:sqlite approach is a dead end for any compiled Bun host (which includes OpenCode). The plugin needs to use a SQLite binding that brings its own SQLite library, independent of bun:sqlite. Options:

    1. better-sqlite3 (N-API) — standalone SQLite with full extension support, works in any Node/Bun runtime
    2. sql.js (WASM) — pure WASM SQLite, no native dependencies at all
    3. Request OpenCode to call setCustomSQLite before opening any databases — requires upstream OpenCode changes

    Environment

    • OpenCode 1.2.0 (Homebrew, compiled Bun binary)
    • opencode-mem 2.8.9
    • macOS Sequoia (Apple Silicon)
    • Standalone Bun 1.3.9 (works fine when running directly)
  3. tickernelz commented on Feb 20, 2026

    @tickernelz
    Owner

    ✅ Fixed in v2.11.0

    This issue has been resolved by replacing sqlite-vec with hnswlib-wasm - a pure WASM implementation of HNSW (Hierarchical Navigable Small World) algorithm for vector search.

    Why the Breaking Change?

    OpenCode loads bun:sqlite BEFORE plugins run, so Database.setCustomSQLite() always fails with "SQLite already loaded" error. This means even a properly-built dylib with statically-linked sqlite-vec cannot be used. The only viable solution is to remove the native dependency entirely.

    What Changed

    • Removed sqlite-vec dependency (native dylib no longer needed)
    • Vector search now uses hnswlib-wasm (pure WASM, works everywhere)
    • No more macOS-specific SQLite issues
    • No more Homebrew fallback needed

    Migration

    This is a breaking change. Existing vector indices will need to be rebuilt. The plugin will automatically rebuild HNSW indices from your stored memory data on first run.

    Benefits

    • Plug-and-play: No native dependencies, no setup required
    • Cross-platform: Works identically on macOS, Linux, Windows
    • No more SQLite extension loading issues

    Upgrade with: bun update opencode-mem or let OpenCode auto-update on next restart.

  4. added a commit that references this issue on Feb 21, 2026
    3ad0f28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions