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` performs the same consistency check as `table_target`: the given `primary_key` must equal `table_schema.primary_key`. This variant registers a table referenced as a relationship endpoint; a mismatched key would corrupt relationship endpoint resolution, so it raises before declaring anything.

Source

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

        managed_by=managed_by,
    )
    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 (no records flow into this declaration's
    own handler — typically used to register a table that is referenced as a
    relationship endpoint by other handlers).
    """
    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 {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",
    managed_by: target.ManagedBy = target.ManagedBy.SYSTEM,

View on GitHub (pinned to e84aa99b32)

Solutions

1. Pass `primary_key=table_schema.primary_key` or omit and let the schema's key be used.
2. Regenerate the schema so its primary key matches the value you intend to pass.
3. For relationship-endpoint registration, derive the key from the same schema object used by the main table target.

Example fix

// before
declare_table_target(db, "Person", person_schema, primary_key="uid")  # schema uses "id"
// after
declare_table_target(db, "Person", person_schema, primary_key=person_schema.primary_key)

if table_schema is not None:
    assert primary_key == table_schema.primary_key
await falkordb.declare_table_target(db, name, table_schema, primary_key=table_schema.primary_key)

try:
    await falkordb.declare_table_target(db, name, table_schema, primary_key=pk)
except ValueError as e:
    if "does not match schema's" in str(e):
        logging.error("Use the schema's primary_key for relationship-endpoint tables: %s", e)
    raise

When it happens

Trigger: Calling `declare_table_target(db, name, table_schema, primary_key="x")` where `"x" != table_schema.primary_key`.

Common situations: Registering a shared node table for relationships with a hand-typed primary key that drifted from the schema; copy-pasting a `declare_table_target` call between tables with different keys; defaulting to `"id"` while the schema uses a domain-specific key.

Related errors

• primary_key {primary_key!r} does not match the schema's decl
• 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/49dfbde51cb18968. Report an issue: GitHub.