unslothai/unsloth · error · RagExtensionUnavailable

RAG unavailable: sqlite-vec extension could not be loaded

Error message

RAG unavailable: sqlite-vec extension could not be loaded

What it means

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.

Source

Thrown at studio/backend/storage/rag_db.py:294

    # the queued follow-up request; it replaced a flag that only recorded rebuilds
    if job_cols and "successor_kind" not in job_cols:
        conn.execute("ALTER TABLE linked_folder_sync_jobs ADD COLUMN successor_kind TEXT")
        if "rebuild_requested" in job_cols:
            conn.execute(
                "UPDATE linked_folder_sync_jobs SET successor_kind='rebuild' "
                "WHERE rebuild_requested=1"
            )
    # vanished paths already granted their one grace pass before removal
    folder_cols = {r[1] for r in conn.execute("PRAGMA table_info(linked_folders)").fetchall()}
    if folder_cols and "withheld_paths" not in folder_cols:
        conn.execute("ALTER TABLE linked_folders ADD COLUMN withheld_paths TEXT")


def get_connection() -> sqlite3.Connection:
    """Open rag.db (WAL + sqlite-vec loaded, schema created once). Raises if the extension is unavailable."""
    global _schema_ready, _extension_loaded
    if not RAG_AVAILABLE:
        raise RagExtensionUnavailable(_RAG_UNAVAILABLE_MSG)

    db_path = rag_db_path()
    ensure_dir(db_path.parent)
    conn = sqlite3.connect(str(db_path))
    conn.row_factory = sqlite3.Row
    # Wait for a lock instead of erroring immediately: a figure/scan-heavy ingest can
    # hold its connection across many seconds of vision calls, and a concurrent ingest
    # or autoinject read would otherwise hit "database is locked".
    conn.execute("PRAGMA busy_timeout = 5000")
    try:
        conn.enable_load_extension(True)
        sqlite_vec.load(conn)
        conn.enable_load_extension(False)
    except Exception as exc:  # noqa: BLE001
        conn.close()
        _warn_unavailable_once(exc)
        raise RagExtensionUnavailable(_RAG_UNAVAILABLE_MSG) from exc
    # Set before the schema step: the library loaded, so RAG runs on this machine

View on GitHub (pinned to 203007d190)

Solutions

1. Install/repair sqlite-vec: pip install sqlite-vec (or add the project's rag extra).
2. Verify it loads in isolation: python -c "import sqlite_vec" and check the wheel matches your platform (musl vs glibc).
3. Restart the Studio process afterwards — RAG_AVAILABLE is decided at import time.
4. If RAG is optional for you, disable RAG features so the calls stop reaching get_connection().

Example fix

# before
$ python -c "import sqlite_vec"
ModuleNotFoundError: No module named 'sqlite_vec'

# after
$ pip install sqlite-vec
$ python -c "import sqlite_vec; print('ok')"
ok

# Run once at deploy time; gate RAG features on success
import importlib.util
RAG_OK = importlib.util.find_spec('sqlite_vec') is not None
if not RAG_OK:
    disable_rag_features()

def rag_available() -> bool:
    try:
        import sqlite_vec  # noqa: F401
        return True
    except Exception:
        return False

from storage.rag_db import RagExtensionUnavailable
try:
    results = rag_query(q)
except RagExtensionUnavailable:
    results = []  # or raise a feature-off signal to the UI
    log.warning('RAG disabled on this host: sqlite-vec unavailable')

When it happens

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

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

Related errors

• GPU selection is unavailable on this host: {exc}
• Speech-to-text needs PyTorch, Transformers, and PyAV. Run `u
• RAG is unavailable: the sqlite-vec extension could not be lo
• NeMo Data Designer Hugging Face integration is not installed
• Requested GPU {wanted} but none of them are visible to this

AI-assisted analysis of unslothai/unsloth@203007d190 (2026-08-15). Data as JSON: /api/errors/d61b66a3bad727ef. Report an issue: GitHub.