unslothai/unsloth · error · HTTPException

RAG is unavailable: the sqlite-vec extension could not be lo

Error message

RAG is unavailable: the sqlite-vec extension could not be loaded.

What it means

The studio backend's RAG (retrieval-augmented generation) feature needs the sqlite-vec SQLite extension for vector search. _require_rag() gates every RAG endpoint: if rag_db.rag_available() is false — either the sqlite-vec Python package was never imported or its native library will not load — the endpoint returns HTTP 503 with this detail instead of an unhandled 500 traceback on connection open. rag_db logs a warn-once so repeated polls stay quiet.

Source

Thrown at studio/backend/routes/rag.py:57

logger = logging.getLogger(__name__)

router = APIRouter()


_UNAVAILABLE_DETAIL = "RAG is unavailable: the sqlite-vec extension could not be loaded."


def _require_rag() -> None:
    """Gate an endpoint on RAG being runnable here.

    Covers both halves of unavailable: sqlite-vec never imported, and it imported but
    its native library will not load. 503 with a stated reason rather than the 500 plus
    traceback a raising connection would produce, and rag_db's warn-once keeps the log
    quiet however often this fires.
    """
    if not rag_db.rag_available():
        raise HTTPException(status_code = 503, detail = _UNAVAILABLE_DETAIL)


@contextmanager
def _rag_unavailable_as_503(cleanup_path: str | None = None) -> Iterator[None]:
    """Report RagExtensionUnavailable as the same 503, wherever it is raised.

    _require_rag() has normally answered for the session already; this closes the window
    where the very first request is the one that discovers the missing library, and it
    reaches the connections ingestion opens for itself. ``cleanup_path`` removes an
    upload that was saved before the failure, so nothing is orphaned in the uploads
    root. Real database errors are left alone.
    """
    try:
        yield
    except rag_db.RagExtensionUnavailable as exc:
        _remove_stored_upload(cleanup_path)
        raise HTTPException(status_code = 503, detail = _UNAVAILABLE_DETAIL) from exc

View on GitHub (pinned to 203007d190)

Solutions

1. Install the extension in the backend environment: pip install sqlite-vec (matching the platform and Python version).
2. Verify import and load in the same interpreter: python -c "import sqlite_vec; c=sqlite3.connect(':memory:'); c.enable_load_extension(True); sqlite_vec.load(c)".
3. If the wheel loads elsewhere but not in the app, rebuild the venv on the same OS/arch as the server runs.
4. Frontend should treat 503 from RAG routes as 'feature unavailable' and surface an install/enable prompt, not retry.

Example fix

# before: RAG endpoints raise sqlite3.OperationalError / 500
# after (env fix)
pip install sqlite-vec
# route now returns 200 once rag_db.rag_available() is true

import sqlite3
try:
    import sqlite_vec
    c = sqlite3.connect(":memory:")
    c.enable_load_extension(True)
    sqlite_vec.load(c)
    RAG_OK = True
except Exception:
    RAG_OK = False
if not RAG_OK:
    disable_rag_ui()  # show install guidance instead of calling endpoints

resp = await fetch('/api/rag/knowledge-bases');
if (resp.status === 503) { enterRagUnavailableMode(); return; }

When it happens

Trigger: Any RAG route call (knowledge-base list/create, upload, search) when sqlite-vec is missing from the venv, or the installed wheel's native binary does not match the environment (wrong platform/Python build), so loading the extension per-connection fails.

Common situations: Fresh install or migration where the 'sqlite-vec' dependency was not installed; the venv was rebuilt on a different OS/arch so the cached wheel is incompatible; sqlite runtime lacks loadable-extension support; a deployment image that pruned native wheels.

Related errors

• Unsupported file type '{ext}'. Allowed: {sorted(config.UPLOA
• File exceeds the {cap // (1024 * 1024)} MB upload limit.
• Uploaded file is empty.
• Native path grant is required.
• Dropped file could not be read.

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