cocoindex-io/cocoindex · error · ValueError

vec0 virtual tables require at least one float[N] vector col

Error message

vec0 virtual tables require at least one float[N] vector column

What it means

A `vec0` virtual table must contain at least one `float[N]` vector column — that is the entire point of the vec0 module. `_validate_vec0_config` scans the table schema columns and raises `ValueError` when none of the column types start with `float[`, i.e. a vec0 table was declared with only scalar columns.

Source

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

        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:
        raise ValueError(
            f"vec0 virtual tables require exactly one primary key column, "
            f"got {len(table_schema.primary_key)}: {table_schema.primary_key}"
        )
    pk_col_name = table_schema.primary_key[0]
    pk_col_type = table_schema.columns[pk_col_name].type
    if pk_col_type != "INTEGER":
        raise ValueError(

View on GitHub (pinned to e84aa99b32)

Solutions

1. Add a float[N] vector column to the schema (e.g. via `VectorSchemaProvider` in `column_overrides` or a vector-typed field in the record)
2. Remove `Vec0TableDef` and use a regular table definition if no vector column is needed
3. Check that `column_overrides` is not overriding the embedding column to a scalar type

Example fix

// before
column_overrides={"embedding": sqlite.SqliteType.TEXT}
// after
column_overrides={"embedding": sqlite.VectorSchemaProvider(dim=384)}

has_vec = any(str(c.type).startswith("float[") for c in schema.columns.values())
assert has_vec, "vec0 table needs at least one float[N] vector column"

def has_vector_column(columns: dict) -> bool:
    return any(str(c.type).startswith("float[") for c in columns.values())

try:
    target = sqlite.table_target(..., virtual_table_def=Vec0TableDef(...))
except ValueError as e:
    if "require at least one float[N]" in e.args[0]:
        add_embedding_column_to_schema()
    else:
        raise

When it happens

Trigger: Constructing a `Vec0TableDef` for a table schema whose columns are all scalar (str/int/etc.); a `column_overrides` mapping that accidentally replaced the vector column with a plain type; forgetting to include the embedding field in the record type.

Common situations: Refactoring a record type and dropping the embeddings field while keeping `Vec0TableDef`; overriding the vector column type via `column_overrides` to a scalar SqliteType; copying vec0 setup without actually adding an embedding column.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Partition key columns not in schema: {invalid_partition}
• Auxiliary columns not in schema: {invalid_aux}
• vec0 virtual tables require exactly one primary key column,
• VectorSchemaProvider is required for NumPy ndarray type.
• Invalid vector dimension: {vector_schema.size}

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