{"record":{"id":"eb5bcb84bdaf3cfb","repo":"headroomlabs-ai/headroom","slug":"sqlite-vec-is-required-for-sqlitevectorindex-inst","errorCode":null,"errorMessage":"sqlite-vec is required for SQLiteVectorIndex. Install with: pip install sqlite-vec\nNote: Requires Python built with loadable extension support. On macOS, use Homebrew Python: brew install python","messagePattern":"sqlite-vec is required for SQLiteVectorIndex\\. Install with: pip install sqlite-vec\nNote: Requires Python built with loadable extension support\\. On macOS, use Homebrew Python: brew install python","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"critical","filePath":"headroom/memory/adapters/sqlite_vector.py","lineNumber":222,"sourceCode":"\n    def __init__(\n        self,\n        dimension: int = 384,\n        db_path: str | Path = \"vectors.db\",\n        page_cache_size_kb: int = 8192,\n    ) -> None:\n        \"\"\"Initialize the SQLite vector index.\n\n        Args:\n            dimension: Embedding dimension. Default 384 for MiniLM.\n            db_path: Path to SQLite database file.\n            page_cache_size_kb: SQLite page cache size in KB. Default 8MB.\n\n        Raises:\n            ImportError: If sqlite-vec is not available.\n        \"\"\"\n        if not _check_sqlite_vec_available():\n            raise ImportError(\n                \"sqlite-vec is required for SQLiteVectorIndex. \"\n                \"Install with: pip install sqlite-vec\\n\"\n                \"Note: Requires Python built with loadable extension support. \"\n                \"On macOS, use Homebrew Python: brew install python\"\n            )\n\n        self._dimension = dimension\n        self._db_path = Path(db_path)\n        self._page_cache_size_kb = page_cache_size_kb\n        self._lock = RLock()\n        self._connections: dict[int, sqlite3.Connection] = {}\n\n        self._init_db()\n\n    def _create_conn(self) -> sqlite3.Connection:\n        \"\"\"Create a SQLite connection with sqlite-vec loaded.\"\"\"\n        conn = sqlite3.connect(str(self._db_path))\n        conn.row_factory = sqlite3.Row","sourceCodeStart":204,"sourceCodeEnd":240,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/memory/adapters/sqlite_vector.py#L204-L240","documentation":"ImportError raised by SQLiteVectorIndex.__init__ when the sqlite-vec extension cannot be loaded — either the package is not installed, or the Python interpreter cannot load SQLite extensions. The message includes install and platform guidance because macOS system Python is commonly built without loadable-extension support.","triggerScenarios":"Constructing SQLiteVectorIndex in an environment where 'pip install sqlite-vec' was never run; using macOS system Python (no extension loading); Python builds where sqlite3 was compiled without SQLITE_OMIT_LOAD_EXTENSION relief; restricted environments blocking extension loading.","commonSituations":"Fresh deployments missing the optional dependency; macOS default /usr/bin/python3; slim Docker images lacking build support; CI matrix differences between local and remote environments.","solutions":["pip install sqlite-vec in the same environment/venv that runs the app.","On macOS, use Homebrew Python (brew install python) or pyenv-built Python, which enable loadable extensions.","If you cannot install extensions, switch to HNSWVectorIndex or another backend that does not need sqlite-vec.","Add sqlite-vec to your requirements/pyproject so deployments install it automatically."],"exampleFix":"# before\nindex = SQLiteVectorIndex(dimension=384, db_path=p)  # ImportError\n\n# after\n# pip install sqlite-vec  (and use a Python with extension support)\nindex = SQLiteVectorIndex(dimension=384, db_path=p)","handlingStrategy":"try-catch","validationCode":"try:\n    import sqlite_vec  # noqa: F401\nexcept ImportError:\n    raise SystemExit(\"Run: pip install sqlite-vec (requires extension-capable Python)\")\nindex = SQLiteVectorIndex(dimension=384, db_path=p)","typeGuard":null,"tryCatchPattern":"try:\n    index = SQLiteVectorIndex(dimension=384, db_path=p)\nexcept ImportError:\n    index = HNSWVectorIndex(dimension=384)  # fallback backend","preventionTips":["Add sqlite-vec to project dependencies and pin it in CI.","On macOS use Homebrew/pyenv Python; test extension loading in a smoke check at startup.","Document which environments support extension loading before users pick this backend."],"tags":["sqlite-vec","import-error","environment","optional-dependency"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}