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

`TableSchema.__init__` validates that the declared `primary_key` names an actual column in the schema's column mapping. FalkorDB node upserts key records by this column, so a missing primary key is a schema construction error raised immediately with the sorted column list for diagnosis.

Source

Thrown at python/cocoindex/connectors/falkordb/_target.py:342

    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` matching an existing column name, e.g. `primary_key="_id"`.
Add/rename a field in the record type so the primary key column exists.
Check the sorted column list in the message and align the key to one of them.

Example fix

// before
class Doc(NamedTuple):
    doc_id: str
    text: str
TableSchema.from_class(Doc)  # defaults to primary_key="id"
// after
TableSchema.from_class(Doc, primary_key="doc_id")

Defensive patterns

Strategy: validation

Validate before calling

cols = {f.name for f in dataclasses.fields(Row)}
pk = "doc_id"
assert pk in cols, f"primary_key {pk!r} not in {sorted(cols)}"
TableSchema.from_class(Row, primary_key=pk)

Try / catch

try:
    schema = falkordb.TableSchema(Row, primary_key=pk)
except ValueError as e:
    if "not found in columns" in str(e):
        logging.error("Align primary_key with a real field name: %s", e)
    raise

Prevention

Always pass primary_key explicitly; don't rely on the "id" default.
Define the key name as a constant shared by the dataclass and call sites.
Rename fields via search-and-replace across schema and target calls together.

When it happens

Trigger: Constructing `TableSchema(columns, primary_key="key", ...)` or calling `from_class(record_type, primary_key="...")` where the named key is not a field/column name of the record type.

Common situations: Default `primary_key="id"` kept while the dataclass field is named `_id`, `key`, or `uid`; renaming a dataclass field without updating `primary_key`; overriding columns and dropping the key 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

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