cocoindex-io/cocoindex · error · RuntimeError

sqlite-vec extension must be loaded for vec0 virtual tables.

Error message

sqlite-vec extension must be loaded for vec0 virtual tables. Use connect(..., load_vec=True)

What it means

`_validate_vec0_config` runs when creating a vec0 virtual table target and first checks that the sqlite-vec extension was actually loaded on the connection (by inspecting `managed_conn.loaded_extensions`). If not, it raises `RuntimeError` directing the user to `connect(..., load_vec=True)`, because vec0 tables cannot exist without the extension.

Source

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

                value = getattr(row, col_name)

            if value is not None and col.encoder is not None:
                value = col.encoder(value)
            out[col_name] = value
        return out

    def __coco_memo_key__(self) -> str:
        return self._provider.memo_key


def _validate_vec0_config(
    table_schema: TableSchema[Any],
    virtual_table_def: Vec0TableDef,
    managed_conn: ManagedConnection,
) -> None:
    """Validate vec0 virtual table configuration."""
    if _VEC_EXTENSION not in managed_conn.loaded_extensions:
        raise RuntimeError(
            "sqlite-vec extension must be loaded for vec0 virtual tables. "
            "Use connect(..., load_vec=True)"
        )
    has_vector_col = any(
        col_def.type.startswith("float[") for col_def in table_schema.columns.values()
    )
    if not has_vector_col:
        raise ValueError(
            "vec0 virtual tables require at least one float[N] vector column"
        )
    all_cols = set(table_schema.columns.keys())
    invalid_partition = set(virtual_table_def.partition_key_columns) - all_cols
    if invalid_partition:
        raise ValueError(f"Partition key columns not in schema: {invalid_partition}")
    invalid_aux = set(virtual_table_def.auxiliary_columns) - all_cols
    if invalid_aux:
        raise ValueError(f"Auxiliary columns not in schema: {invalid_aux}")
    if len(table_schema.primary_key) != 1:

View on GitHub (pinned to e84aa99b32)

Solutions

Open the connection with `connect(path, load_vec=True)`
Install `sqlite-vec` and confirm import/load succeeds
Verify with a quick check that the extension loads in your SQLite build before running the pipeline

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

conn = sqlite.connect(path, load_vec=True)
assert "vec0" in conn.loaded_extensions, "sqlite-vec failed to load"

Try / catch

try:
    target = sqlite.table_target("vecs", virtual_table_def=Vec0TableDef(...), ...)
except RuntimeError as e:
    if "sqlite-vec extension must be loaded" in str(e):
        install_or_enable_vec()
    else:
        raise

Prevention

Never construct Vec0TableDef targets on connections opened without load_vec=True
Add sqlite-vec to install requirements and verify loading at app startup
Use one connection factory for all environments

When it happens

Trigger: Calling `table_target(...)` with a `Vec0TableDef` on a connection opened without `load_vec=True`; the `sqlite-vec` package missing so loading failed silently at connect time; extension loading blocked by the SQLite build.

Common situations: Vector example code copied without the matching `connect()` options; deployment environment lacking `sqlite-vec`; switching from an in-memory test DB (extension loaded) to a production connect call that omits it.

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/04db9e4940c0e642. Report an issue: GitHub.