cocoindex-io/cocoindex · error · RuntimeError

Table '{table_name}' has vector column(s) {vector_cols}, but

Error message

Table '{table_name}' has vector column(s) {vector_cols}, but sqlite-vec extension is not loaded. Use connect(..., load_vec=True) to enable it.

What it means

`_create_table` refuses to create a regular SQLite table that has vector-typed columns when the sqlite-vec extension is not loaded, since vector columns need the vec0 virtual-table machinery. It lists the offending vector columns in the message and points to `connect(..., load_vec=True)`.

Source

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

    columns_sql = ",\n    ".join(col_defs)
    sql = f"CREATE VIRTUAL TABLE {qualified_name} USING {module_name}(\n    {columns_sql}\n)"

    conn.execute(sql)


def _create_table(
    conn: sqlite3.Connection,
    table_name: str,
    schema: TableSchema[Any],
    *,
    if_not_exists: bool,
    has_vec_extension: bool,
) -> None:
    """Create a table."""
    # Check if vector columns are used but sqlite-vec is not loaded
    vector_cols = [name for name, col in schema.columns.items() if col.is_vector]
    if vector_cols and not has_vec_extension:
        raise RuntimeError(
            f"Table '{table_name}' has vector column(s) {vector_cols}, but sqlite-vec "
            "extension is not loaded. Use connect(..., load_vec=True) to enable it."
        )

    qualified_name = _qualified_table_name(table_name)

    # Build column definitions
    col_defs = []
    for col_name, col in schema.columns.items():
        nullable = (
            "" if col.nullable and col_name not in schema.primary_key else " NOT NULL"
        )
        col_defs.append(f'"{col_name}" {col.type}{nullable}')

    # Build primary key constraint
    pk_cols = ", ".join(f'"{c}"' for c in schema.primary_key)
    col_defs.append(f"PRIMARY KEY ({pk_cols})")

View on GitHub (pinned to e84aa99b32)

Solutions

1. Call `connect(path, load_vec=True)` so the sqlite-vec extension is loaded
2. Install the `sqlite-vec` package if the extension cannot be loaded
3. If vectors are not actually needed, change the column type to a non-vector SqliteType

Example fix

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

if any(getattr(c, "is_vector", False) for c in schema.columns.values()):
    assert conn_options.get("load_vec"), "Vector columns require load_vec=True"

try:
    await app.update()
except RuntimeError as e:
    if "sqlite-vec" in str(e) and "load_vec=True" in str(e):
        conn = sqlite.connect(path, load_vec=True)
    else:
        raise

When it happens

Trigger: Declaring a SQLite table target whose schema contains columns with vector types (e.g. produced by a `VectorSchemaProvider` or `SqliteType` float-vector mapping) while the connection was opened without `load_vec=True`.

Common situations: Adding an embedding column to an existing SQLite-backed pipeline without updating `connect()`; copying a `connect()` call from a non-vector example; forgetting to install `sqlite-vec` so the load silently fails or is skipped.

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

• VectorSchemaProvider is required for NumPy ndarray type.
• sqlite-vec extension required for {module_name} virtual tabl
• sqlite-vec extension must be loaded for vec0 virtual tables.
• VectorSchemaProvider is required for NumPy ndarray type.
• VectorSchemaProvider only supported for ndarray. Got: {pytho

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