cocoindex-io/cocoindex · error · ValueError

Partition key columns not in schema: {invalid_partition}

Error message

Partition key columns not in schema: {invalid_partition}

What it means

The SQLite vec0 virtual table declares partition key columns, but the table schema does not contain columns with those names. CocoIndex validates the vec0 configuration against the declared schema before creating the virtual table, so a partition column that is not a real schema column is rejected up front instead of failing inside sqlite-vec.

Source

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

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


def table_target(

View on GitHub (pinned to e84aa99b32)

Solutions

1. Add the missing column(s) to the table schema (or the record type it derives from) so every partition key column exists.
2. Fix partition_key_columns to reference only existing schema column names (check spelling).
3. Remove obsolete partition key column entries if the column is no longer needed.

Example fix

// before
schema = table_schema(columns=["id", "embedding"], partition_key_columns=["folder"])
// after
schema = table_schema(columns=["id", "embedding", "folder"], partition_key_columns=["folder"])

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

def valid_partition_keys(schema, keys) -> bool:
    return all(k in schema.columns for k in keys)

try:
    target = table_target(schema, virtual_table_def)
except ValueError as e:
    if "Partition key columns not in schema" in str(e):
        # fix schema or partition_key_columns before retrying
        ...

When it happens

Trigger: Calling table_target() for a SQLite vec0 table whose VirtualTableDef.partition_key_columns references a column name not present in the provided table schema's columns mapping (typo, renamed column, or column removed from the schema).

Common situations: Renaming or removing a partition column from the record schema but forgetting to update partition_key_columns; hand-building a VirtualTableDef with stale column names; mismatch between typed row model fields and the explicit schema passed to table_target.

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

• Auxiliary columns not in schema: {invalid_aux}
• 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/3021df6e572873f3. Report an issue: GitHub.