cocoindex-io/cocoindex · error · ValueError

primary_key {primary_key!r} does not match the schema's decl

Error message

primary_key {primary_key!r} does not match the schema's declared primary_key {table_schema.primary_key!r}

What it means

The `table_target` target-state factory validates that the `primary_key` argument matches the `primary_key` recorded in the supplied `TableSchema`. A mismatch would make the keying of target states inconsistent with the schema, so ValueError is raised listing both values.

Source

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

# ---------------------------------------------------------------------------
# Module-level entry points
# ---------------------------------------------------------------------------


def table_target(
    db: ContextKey[ConnectionFactory],
    table_name: str,
    table_schema: TableSchema[RowT] | None = None,
    *,
    primary_key: str = "id",
    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM,
) -> coco.TargetState[_RecordHandler]:
    """Create a ``TargetState`` for a FalkorDB node table (label)."""
    _validate_identifier(table_name, "table name")
    _validate_identifier(primary_key, "primary key")
    if table_schema is not None and table_schema.primary_key != primary_key:
        raise ValueError(
            f"primary_key {primary_key!r} does not match the schema's "
            f"declared primary_key {table_schema.primary_key!r}"
        )
    key = _TableKey(db_key=db.key, table_name=table_name)
    spec = _TableSpec(
        table_schema=table_schema,
        primary_key=primary_key,
        is_relation=False,
        from_label=None,
        from_pk_field=None,
        to_label=None,
        to_pk_field=None,
        managed_by=managed_by,
    )
    return _table_provider.target_state(key, spec)


def declare_table_target(

View on GitHub (pinned to e84aa99b32)

Solutions

1. Omit `primary_key` so the schema's key is used, or pass `primary_key=table_schema.primary_key`.
2. Fix the `from_class(..., primary_key=...)` call so both sides agree.
3. Centralize the key name in one constant used by both schema and target calls.

Example fix

// before
table_target(db, "Doc", schema, primary_key="id")  # schema.primary_key == "doc_id"
// after
table_target(db, "Doc", schema)  # defaults to schema.primary_key

if table_schema is not None:
    assert primary_key == table_schema.primary_key, \
        f"pk mismatch: {primary_key!r} vs schema {table_schema.primary_key!r}"
target = falkordb.table_target(db, name, table_schema)

try:
    target = falkordb.table_target(db, name, table_schema, primary_key=pk)
except ValueError as e:
    if "does not match the schema" in str(e):
        logging.error("Omit primary_key or use table_schema.primary_key: %s", e)
    raise

When it happens

Trigger: Calling `falkordb.table_target(db, name, table_schema, primary_key="other_key")` (or via `mount_table_target`) where `primary_key` differs from `table_schema.primary_key`.

Common situations: Building the schema with `primary_key="doc_id"` but keeping the default `primary_key="id"` at the target call; two call sites where one was updated after a rename; composing the call programmatically with a stale key variable.

Related errors

• primary_key {primary_key!r} does not match schema's {table_s
• primary_key {primary_key!r} not found in columns ({sorted(co
• row is missing primary key field {self._primary_key!r}
• Primary key column '{pk}' not found in columns: {list(self.c
• build_node_upsert requires at least one primary key field

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