cocoindex-io/cocoindex · error · ValueError

primary_key {primary_key!r} does not match schema's {table_s

Error message

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

What it means

declare_table_target() checks that the primary_key argument agrees with the provided table_schema.primary_key before declaring the table target state. A mismatch means the declared relationship endpoint would use a different key than the schema, so the call is rejected.

Source

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

    )
    return _table_provider.target_state(key, spec)


def declare_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,
) -> TableTarget[RowT, coco.PendingS]:
    """Declare a node table target.

    Use this for tables that exist only as relationship endpoints — no
    records flow into this declaration's own handler.
    """
    if table_schema is not None and table_schema.primary_key != primary_key:
        raise ValueError(
            f"primary_key {primary_key!r} does not match schema's "
            f"{table_schema.primary_key!r}"
        )
    pk = table_schema.primary_key if table_schema is not None else primary_key
    provider = coco.declare_target_state_with_child(
        table_target(
            db, table_name, table_schema, primary_key=pk, managed_by=managed_by
        )
    )
    return TableTarget(provider, table_schema, table_name, pk)


async def mount_table_target(
    db: ContextKey[ConnectionFactory],
    table_name: str,
    table_schema: TableSchema[RowT] | None = None,
    *,
    primary_key: str = "id",

View on GitHub (pinned to e84aa99b32)

Solutions

Pass primary_key=schema.primary_key.
Drop the explicit primary_key and rely on table_schema alone (pk falls back to schema's).
Fix the schema's primary_key if it is wrong.

Example fix

// before
neo4j.declare_table_target(db, "Person", primary_key="id", table_schema=schema)
// after
neo4j.declare_table_target(db, "Person", primary_key=schema.primary_key, table_schema=schema)

Defensive patterns

Strategy: validation

Validate before calling

pk = table_schema.primary_key if table_schema is not None else "id"
neo4j.declare_table_target(db, "Person", primary_key=pk, table_schema=table_schema)

Try / catch

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

Prevention

Derive primary_key from the schema object rather than hardcoding "id".
Centralize table definitions so endpoint tables share the same schema instance.

When it happens

Trigger: Calling declare_table_target(..., primary_key="id", table_schema=schema) where schema.primary_key differs.

Common situations: Declaring a relationship-endpoint table using defaults while the shared schema declares another PK; copying a call from another table with a different PK.

Related errors

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