cocoindex-io/cocoindex · error · ImportError

sqlite-vec is required for vector support. Install it with:

Error message

sqlite-vec is required for vector support. Install it with: pip install sqlite-vec

What it means

The connection is configured for vector support, which requires the optional sqlite-vec extension. The package could not be imported (it is not installed), so CocoIndex raises an ImportError pointing to the install command, unless the caller opted to ignore the missing extension.

Source

Thrown at python/cocoindex/connectors/sqlite/_target.py:1384

        ```
    """
    managed_conn = connect(database, timeout=timeout, load_vec=load_vec, **kwargs)
    try:
        yield managed_conn
    finally:
        managed_conn.close()


def _load_sqlite_vec(
    managed_conn: ManagedConnection, *, ignore_error: bool = False
) -> None:
    """Load the sqlite-vec extension into a managed connection."""
    try:
        import sqlite_vec  # type: ignore
    except ImportError as e:
        if ignore_error:
            return
        raise ImportError(
            "sqlite-vec is required for vector support. "
            "Install it with: pip install sqlite-vec"
        ) from e

    try:
        managed_conn._conn.enable_load_extension(True)
        sqlite_vec.load(managed_conn._conn)
        managed_conn._conn.enable_load_extension(False)
        managed_conn._loaded_extensions.add(_VEC_EXTENSION)
    except sqlite3.OperationalError:
        if ignore_error:
            return
        raise


__all__ = [
    "ColumnDef",
    "ManagedConnection",

View on GitHub (pinned to e84aa99b32)

Solutions

1. Run: pip install sqlite-vec (or install the cocoindex extra that includes it).
2. If using uv: uv add sqlite-vec, then rebuild/reinstall the environment.
3. If vector support is not actually needed, remove the vector/vec0 configuration from the table target so the extension is not required.

Example fix

// before (error)
import cocoindex
conn = sqlite_target.connect(...)  # vector table, sqlite-vec missing
// after
# pip install sqlite-vec
conn = sqlite_target.connect(...)

import importlib.util
if importlib.util.find_spec("sqlite_vec") is None:
    raise SystemExit("sqlite-vec not installed; run: pip install sqlite-vec")

def sqlite_vec_available() -> bool:
    import importlib.util
    return importlib.util.find_spec("sqlite_vec") is not None

try:
    conn = connect(...)
except ImportError as e:
    if "sqlite-vec" in str(e):
        subprocess.run([sys.executable, "-m", "pip", "install", "sqlite-vec"], check=True)
        conn = connect(...)

When it happens

Trigger: Declaring a vec0/vector-capable SQLite table target and connecting without the sqlite-vec package installed in the current environment; installing cocoindex without the relevant extras; running in a fresh venv/CI container that lacks the dependency.

Common situations: New machine or CI runner where the example works locally but sqlite-vec was never installed; switching Python interpreters/venvs; dependency not pinned in requirements after enabling vector support.

Understand the failure class

Background: "X is not installed. Please install it with pip install Y": missing optional dependency errors — ImportError/ValueError raised when a library's optional extra was never installed — this error's family across 22 libraries.

Related errors

• aiobotocore is required to use the Amazon S3 source connecto
• aiomysql is required for async Doris connections. Install it
• sqlite-vec extension required for {module_name} virtual tabl
• Table '{table_name}' has vector column(s) {vector_cols}, but
• sqlite-vec extension must be loaded for vec0 virtual tables.

AI-assisted analysis of cocoindex-io/cocoindex@e84aa99b32 (2026-09-08). Data as JSON: /api/errors/1a5aca80d54ebde3. Report an issue: GitHub.