{"record":{"id":"d61b66a3bad727ef","repo":"unslothai/unsloth","slug":"rag-unavailable-sqlite-vec-extension-could-not-be","errorCode":null,"errorMessage":"RAG unavailable: sqlite-vec extension could not be loaded","messagePattern":"RAG unavailable: sqlite-vec extension could not be loaded","errorType":"exception","errorClass":"RagExtensionUnavailable","httpStatus":503,"severity":"error","filePath":"studio/backend/storage/rag_db.py","lineNumber":294,"sourceCode":"    # the queued follow-up request; it replaced a flag that only recorded rebuilds\n    if job_cols and \"successor_kind\" not in job_cols:\n        conn.execute(\"ALTER TABLE linked_folder_sync_jobs ADD COLUMN successor_kind TEXT\")\n        if \"rebuild_requested\" in job_cols:\n            conn.execute(\n                \"UPDATE linked_folder_sync_jobs SET successor_kind='rebuild' \"\n                \"WHERE rebuild_requested=1\"\n            )\n    # vanished paths already granted their one grace pass before removal\n    folder_cols = {r[1] for r in conn.execute(\"PRAGMA table_info(linked_folders)\").fetchall()}\n    if folder_cols and \"withheld_paths\" not in folder_cols:\n        conn.execute(\"ALTER TABLE linked_folders ADD COLUMN withheld_paths TEXT\")\n\n\ndef get_connection() -> sqlite3.Connection:\n    \"\"\"Open rag.db (WAL + sqlite-vec loaded, schema created once). Raises if the extension is unavailable.\"\"\"\n    global _schema_ready, _extension_loaded\n    if not RAG_AVAILABLE:\n        raise RagExtensionUnavailable(_RAG_UNAVAILABLE_MSG)\n\n    db_path = rag_db_path()\n    ensure_dir(db_path.parent)\n    conn = sqlite3.connect(str(db_path))\n    conn.row_factory = sqlite3.Row\n    # Wait for a lock instead of erroring immediately: a figure/scan-heavy ingest can\n    # hold its connection across many seconds of vision calls, and a concurrent ingest\n    # or autoinject read would otherwise hit \"database is locked\".\n    conn.execute(\"PRAGMA busy_timeout = 5000\")\n    try:\n        conn.enable_load_extension(True)\n        sqlite_vec.load(conn)\n        conn.enable_load_extension(False)\n    except Exception as exc:  # noqa: BLE001\n        conn.close()\n        _warn_unavailable_once(exc)\n        raise RagExtensionUnavailable(_RAG_UNAVAILABLE_MSG) from exc\n    # Set before the schema step: the library loaded, so RAG runs on this machine","sourceCodeStart":276,"sourceCodeEnd":312,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/storage/rag_db.py#L276-L312","documentation":"RagExtensionUnavailable raised at the top of get_connection(): the module-level RAG_AVAILABLE flag is False, meaning the import-time attempt to load the sqlite-vec extension already failed (import sqlite_vec missing or its shared library unloadable). Every subsequent RAG connection attempt short-circuits with this message rather than retrying the import.","triggerScenarios":"Any RAG feature call (ingest, query, autoinject read) on an environment where the sqlite-vec package is not installed or its .so/.dll cannot load; fresh deploy that installed requirements without the RAG extras; OS/glibc mismatch on the vendored binary.","commonSituations":"pip install without the rag extra; Alpine/musl images where manylinux wheels don't load; Python upgraded so the previously installed extension no longer matches.","solutions":["Install/repair sqlite-vec: pip install sqlite-vec (or add the project's rag extra).","Verify it loads in isolation: python -c \"import sqlite_vec\" and check the wheel matches your platform (musl vs glibc).","Restart the Studio process afterwards — RAG_AVAILABLE is decided at import time.","If RAG is optional for you, disable RAG features so the calls stop reaching get_connection()."],"exampleFix":"# before\n$ python -c \"import sqlite_vec\"\nModuleNotFoundError: No module named 'sqlite_vec'\n\n# after\n$ pip install sqlite-vec\n$ python -c \"import sqlite_vec; print('ok')\"\nok","handlingStrategy":"validation","validationCode":"# Run once at deploy time; gate RAG features on success\nimport importlib.util\nRAG_OK = importlib.util.find_spec('sqlite_vec') is not None\nif not RAG_OK:\n    disable_rag_features()","typeGuard":"def rag_available() -> bool:\n    try:\n        import sqlite_vec  # noqa: F401\n        return True\n    except Exception:\n        return False","tryCatchPattern":"from storage.rag_db import RagExtensionUnavailable\ntry:\n    results = rag_query(q)\nexcept RagExtensionUnavailable:\n    results = []  # or raise a feature-off signal to the UI\n    log.warning('RAG disabled on this host: sqlite-vec unavailable')","preventionTips":["Include sqlite-vec in deployment requirements; smoke-test it in the image build","Remember RAG_AVAILABLE is fixed at import time — restart after installing","Disable RAG-dependent UI when the extension is known-absent, instead of letting calls fail"],"tags":["rag","sqlite-vec","native-extension","import-error","environment"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}