cocoindex-io/cocoindex · error · RuntimeError

sqlite-vec extension required for {module_name} virtual tabl

Error message

sqlite-vec extension required for {module_name} virtual tables

What it means

Creating a `vec0` virtual table requires the sqlite-vec extension to be loaded into the connection. `_create_virtual_table` checks `has_vec_extension` before issuing `CREATE VIRTUAL TABLE ... USING vec0(...)` and raises `RuntimeError` when the extension is missing, because SQLite cannot parse the `vec0` module without it.

Source

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

    has_vec_extension: bool,
) -> None:
    """
    Create a virtual table.

    For vec0, the syntax is:
        CREATE VIRTUAL TABLE name USING vec0(
            id integer primary key,
            embedding float[384],
            year integer partition key,
            metadata text,
            +auxiliary_data text
        )
    """
    module_name = virtual_table_def.module_name

    # Validate extension is loaded
    if module_name == "vec0" and not has_vec_extension:
        raise RuntimeError(
            f"sqlite-vec extension required for {module_name} virtual tables"
        )

    qualified_name = _qualified_table_name(table_name)

    # Build column definitions for virtual table syntax
    col_defs = []
    partition_keys = set(virtual_table_def.partition_key_columns)
    auxiliary_cols = set(virtual_table_def.auxiliary_columns)

    for col_name, col_def in schema.columns.items():
        parts = []

        # Add + prefix for auxiliary columns
        if col_name in auxiliary_cols:
            parts.append(f"+{col_name}")
        else:
            parts.append(col_name)

View on GitHub (pinned to e84aa99b32)

Solutions

Open the connection with `connect(path, load_vec=True)`
Add `sqlite-vec` to your project dependencies so the extension is available to load
Verify the SQLite build supports loading extensions (some system/distro builds disable extension loading)

Example fix

// before
conn = sqlite.connect("app.db")
// after
conn = sqlite.connect("app.db", load_vec=True)

Defensive patterns

Strategy: validation

Validate before calling

conn = sqlite.connect(path, load_vec=True)
assert "vec0" in conn.loaded_extensions

Try / catch

try:
    await app.update()
except RuntimeError as e:
    if "sqlite-vec extension required" in str(e):
        # reopen connection with load_vec=True or install sqlite-vec
        ...
    else:
        raise

Prevention

Always pass load_vec=True when any table uses Vec0TableDef or vector columns
Add sqlite-vec to project dependencies and CI
Sanity-check extension loading at startup in a smoke test

When it happens

Trigger: Syncing a table target defined with `Vec0TableDef` (module `vec0`) to a SQLite connection opened without `connect(..., load_vec=True)`, or an environment where the `sqlite-vec` package is not installed so the extension cannot be loaded even when requested.

Common situations: Forgetting `load_vec=True` in `connect()` after adding a vector column to a previously plain SQLite table; deploying to a machine where `sqlite-vec` is not in the dependency list; using a system SQLite build that cannot load extensions.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

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