cocoindex-io/cocoindex · error · ValueError

primary_key {primary_key!r} not found in columns ({sorted(co

Error message

primary_key {primary_key!r} not found in columns ({sorted(columns)!r})

What it means

This ValueError is raised by TableSchema's __init__ when the designated primary_key column is not present among the schema's columns. The primary key anchors row identity and change detection, so it must name an existing column. The message lists the available column names sorted, to make the typo obvious.

Source

Thrown at python/cocoindex/connectors/neo4j/_target.py:382

    Single-field primary key (named via ``primary_key``, default ``"id"``).
    Compound primary keys are not supported in v1.0.
    """

    columns: dict[str, ColumnDef]
    primary_key: str
    row_type: type[RowT] | None

    def __init__(
        self,
        columns: dict[str, ColumnDef],
        *,
        primary_key: str = "id",
        row_type: type[RowT] | None = None,
    ) -> None:
        for col_name in columns:
            _validate_identifier(col_name, "column name")
        if primary_key not in columns:
            raise ValueError(
                f"primary_key {primary_key!r} not found in columns "
                f"({sorted(columns)!r})"
            )
        self.columns = columns
        self.primary_key = primary_key
        self.row_type = row_type

    @property
    def value_field_names(self) -> list[str]:
        """Column names other than the primary key, in declared order."""
        return [c for c in self.columns if c != self.primary_key]

    @classmethod
    async def from_class(
        cls,
        record_type: type[RowT],
        *,
        primary_key: str = "id",

View on GitHub (pinned to e84aa99b32)

Solutions

Pass primary_key="<existing column name>" matching one of the columns.
Add an 'id' field to the record type if you want the default.
Print the columns list (shown in the error) and fix the key name typo.

Example fix

// before
TableSchema(columns={"uid": ..., "name": ...}, primary_key="id")
// after
TableSchema(columns={"uid": ..., "name": ...}, primary_key="uid")

Defensive patterns

Strategy: validation

Validate before calling

if primary_key not in columns:
    raise ValueError(f"primary_key {primary_key!r} must be one of {sorted(columns)}")

Try / catch

try:
    schema = TableSchema(columns=columns, primary_key=pk)
except ValueError as e:
    raise RuntimeError(f"bad primary key; available columns: {sorted(columns)}") from e

Prevention

Default primary_key should match an actual id field in the record type
When renaming a key field, update primary_key in the same commit
Validate primary key presence in a unit test per schema

When it happens

Trigger: Constructing TableSchema(columns=[...], primary_key="key") where "key" is not in columns — e.g. a default primary_key="id" while the record type has no 'id' field, or passing column_overrides that renamed/removed the key column.

Common situations: Renaming the id field in a dataclass without updating primary_key; relying on the default primary_key="id" for a record with a differently named key; building columns from a subset of record fields that excluded the key.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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