{"record":{"id":"967d770d0014ef43","repo":"unslothai/unsloth","slug":"rag-is-unavailable-the-sqlite-vec-extension-could","errorCode":null,"errorMessage":"RAG is unavailable: the sqlite-vec extension could not be loaded.","messagePattern":"RAG is unavailable: the sqlite-vec extension could not be loaded\\.","errorType":"http","errorClass":"HTTPException","httpStatus":503,"severity":"error","filePath":"studio/backend/routes/rag.py","lineNumber":57,"sourceCode":"\nlogger = logging.getLogger(__name__)\n\nrouter = APIRouter()\n\n\n_UNAVAILABLE_DETAIL = \"RAG is unavailable: the sqlite-vec extension could not be loaded.\"\n\n\ndef _require_rag() -> None:\n    \"\"\"Gate an endpoint on RAG being runnable here.\n\n    Covers both halves of unavailable: sqlite-vec never imported, and it imported but\n    its native library will not load. 503 with a stated reason rather than the 500 plus\n    traceback a raising connection would produce, and rag_db's warn-once keeps the log\n    quiet however often this fires.\n    \"\"\"\n    if not rag_db.rag_available():\n        raise HTTPException(status_code = 503, detail = _UNAVAILABLE_DETAIL)\n\n\n@contextmanager\ndef _rag_unavailable_as_503(cleanup_path: str | None = None) -> Iterator[None]:\n    \"\"\"Report RagExtensionUnavailable as the same 503, wherever it is raised.\n\n    _require_rag() has normally answered for the session already; this closes the window\n    where the very first request is the one that discovers the missing library, and it\n    reaches the connections ingestion opens for itself. ``cleanup_path`` removes an\n    upload that was saved before the failure, so nothing is orphaned in the uploads\n    root. Real database errors are left alone.\n    \"\"\"\n    try:\n        yield\n    except rag_db.RagExtensionUnavailable as exc:\n        _remove_stored_upload(cleanup_path)\n        raise HTTPException(status_code = 503, detail = _UNAVAILABLE_DETAIL) from exc\n","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/unslothai/unsloth/blob/203007d19051dcd2ae33876786d117c99f6b0368/studio/backend/routes/rag.py#L39-L75","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install the extension in the backend environment: pip install sqlite-vec (matching the platform and Python version).","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)\".","If the wheel loads elsewhere but not in the app, rebuild the venv on the same OS/arch as the server runs.","Frontend should treat 503 from RAG routes as 'feature unavailable' and surface an install/enable prompt, not retry."],"exampleFix":"# before: RAG endpoints raise sqlite3.OperationalError / 500\n# after (env fix)\npip install sqlite-vec\n# route now returns 200 once rag_db.rag_available() is true","handlingStrategy":"fallback","validationCode":"import sqlite3\ntry:\n    import sqlite_vec\n    c = sqlite3.connect(\":memory:\")\n    c.enable_load_extension(True)\n    sqlite_vec.load(c)\n    RAG_OK = True\nexcept Exception:\n    RAG_OK = False\nif not RAG_OK:\n    disable_rag_ui()  # show install guidance instead of calling endpoints","typeGuard":null,"tryCatchPattern":"resp = await fetch('/api/rag/knowledge-bases');\nif (resp.status === 503) { enterRagUnavailableMode(); return; }","preventionTips":["Pin sqlite-vec in the deployment requirements and smoke-test its load at startup.","Treat 503 from RAG routes as a capability flag: hide RAG UI instead of retrying.","Rebuild venvs on the same OS/arch as production to keep the native wheel loadable."],"tags":["http-503","rag","sqlite-vec","dependency","studio-backend"],"backgroundTag":null,"analyzedSha":"203007d19051dcd2ae33876786d117c99f6b0368","analyzedAt":"2026-08-15T02:48:39.846Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}