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

table_target() validates consistency between the explicit primary_key argument and the optional TableSchema. If both are given and disagree, the library cannot determine which field identifies nodes, so it raises ValueError rather than silently picking one.

Source

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

# ---------------------------------------------------------------------------
# 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 Neo4j 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

Make primary_key match table_schema.primary_key (e.g. primary_key=schema.primary_key).
Omit table_schema if you intend to rely solely on the explicit primary_key.
Update the TableSchema definition if the explicit primary_key is the intended one.

Example fix

// before
coco.neo4j.table_target(db, "Person", primary_key="id", table_schema=schema)  # schema.primary_key == "email"
// after
coco.neo4j.table_target(db, "Person", primary_key=schema.primary_key, table_schema=schema)

Defensive patterns

Strategy: validation

Validate before calling

if table_schema is not None and primary_key != table_schema.primary_key:
    primary_key = table_schema.primary_key  # reconcile before calling
coco.neo4j.table_target(db, "Person", primary_key=primary_key, table_schema=table_schema)

Try / catch

try:
    coco.neo4j.table_target(db, name, primary_key=pk, table_schema=schema)
except ValueError as e:
    raise ConfigError("primary_key/table_schema mismatch") from e

Prevention

Pass primary_key=schema.primary_key instead of a literal when a schema is provided.
Adopt one convention: either always schema-driven or always explicit PK, not both.
Add a unit test that builds all table targets from the shared schema registry.

When it happens

Trigger: Calling table_target(db, table_name=..., primary_key="id", table_schema=schema) where schema.primary_key is a different field name.

Common situations: Schema was defined with primary_key="key" while the call site still passes the default primary_key="id"; schema updated after refactoring without updating call sites.

Related errors

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