cocoindex-io/cocoindex · error · ValueError

Primary key column '{pk}' not found in columns: {list(self.c

Error message

Primary key column '{pk}' not found in columns: {list(self.columns.keys())}

What it means

The SQLite table schema validates at construction time that every name in `primary_key` refers to an existing column derived from the record type. This fails fast because a primary key referencing a nonexistent column would produce invalid DELETE/UPDATE SQL later. The error lists the actual available columns to ease diagnosis.

Source

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

        """
        Create a TableSchema from pre-resolved column definitions.

        For constructing from a record type, use the async classmethod
        ``from_class`` instead.

        Args:
            columns: A dict mapping column names to ColumnDef.
            primary_key: List of column names that form the primary key.
            row_type: Optional original record type.
        """
        self.columns = columns
        self.primary_key = primary_key
        self.row_type = row_type

        # Validate primary key columns exist
        for pk in self.primary_key:
            if pk not in self.columns:
                raise ValueError(
                    f"Primary key column '{pk}' not found in columns: {list(self.columns.keys())}"
                )

    @classmethod
    async def from_class(
        cls,
        record_type: type[RowT],
        primary_key: list[str],
        *,
        column_overrides: dict[str, SqliteType | res_schema.VectorSchemaProvider]
        | None = None,
    ) -> "TableSchema[RowT]":
        """
        Create a TableSchema from a record type (dataclass, NamedTuple, or Pydantic model).

        Python types are automatically mapped to SQLite types.

        Args:

View on GitHub (pinned to e84aa99b32)

Solutions

Correct primary_key entries to exactly match field names in the record type (check the column list in the error message).
If fields were renamed, update both the record type and primary_key together.
If column overrides rename the PK column, use the name that appears in the derived columns dict.

Example fix

// before
@dataclasses.dataclass
class Row:
    doc_id: str
    text: str

target = sqlite.table_target(record_type=Row, primary_key=["id"])
// after
target = sqlite.table_target(record_type=Row, primary_key=["doc_id"])

Defensive patterns

Strategy: validation

Validate before calling

import dataclasses
fields = {f.name for f in dataclasses.fields(Row)}
bad = [pk for pk in primary_key if pk not in fields]
if bad:
    raise ValueError(f"primary_key {bad} not fields of {Row.__name__}: {sorted(fields)}")

Try / catch

try:
    target = sqlite.table_target(record_type=Row, primary_key=pk, ...)
except ValueError as e:
    if "not found in columns" in str(e):
        raise ConfigError(f"Fix primary_key {pk}; valid columns are listed in: {e}") from e
    raise

Prevention

Derive primary_key from dataclasses.fields(Row) names instead of hardcoding strings.
Keep record type definitions and primary_key settings in one module so renames stay in sync.
Grep for renamed fields whenever you change the record dataclass.

When it happens

Trigger: Calling `table_target(..., primary_key=["id"])` where the record type has no field named 'id' — due to a typo, renamed field, or a primary_key entry matching a column override name rather than the field name.

Common situations: Renaming a dataclass field without updating primary_key, referencing the DB column name after column renaming/overrides changed it, or copying an example whose record type differs.

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

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