cocoindex-io/cocoindex · error · ValueError

Auxiliary columns not in schema: {invalid_aux}

Error message

Auxiliary columns not in schema: {invalid_aux}

What it means

The vec0 virtual table declares auxiliary columns, but those names are not present in the declared table schema. CocoIndex validates vec0 configuration at table_target() time so auxiliary column mismatches fail early rather than when SQLite creates the virtual table.

Source

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

    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(
            f"vec0 virtual tables require INTEGER primary key, "
            f"got {pk_col_type} for column '{pk_col_name}'"
        )


def table_target(
    db: ContextKey[ManagedConnection],
    table_name: str,
    table_schema: TableSchema[RowT],

View on GitHub (pinned to e84aa99b32)

Solutions

1. Add the missing auxiliary column(s) to the table schema.
2. Correct auxiliary_columns entries to match actual schema column names.
3. Drop auxiliary_columns entries that are no longer needed.

Example fix

// before
virtual_table_def = VirtualTableDef(auxiliary_columns=["source_text"])
schema = table_schema(columns=["id", "embedding"])
// after
schema = table_schema(columns=["id", "embedding", "source_text"])

invalid = set(auxiliary_columns) - set(schema.columns)
if invalid:
    raise ValueError(f"auxiliary columns missing from schema: {invalid}")

def valid_aux_columns(schema, cols) -> bool:
    return all(c in schema.columns for c in cols)

try:
    target = table_target(schema, virtual_table_def)
except ValueError as e:
    if "Auxiliary columns not in schema" in str(e):
        # align auxiliary_columns with schema.columns
        ...

When it happens

Trigger: Calling table_target() for a vec0 table where VirtualTableDef.auxiliary_columns includes a column name absent from table_schema.columns (typo, renamed/removed column, stale definition).

Common situations: Adding an auxiliary column to the vec0 definition but not to the row schema; renaming a schema column without updating auxiliary_columns; copy-pasted table definitions retaining columns from another table.

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}
• vec0 virtual tables require at least one float[N] vector col
• vec0 virtual tables require exactly one primary key column,
• vec0 virtual tables require INTEGER primary key, got {pk_col
• Primary key column '{pk}' not found in columns: {list(self.c

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