cocoindex-io/cocoindex · error · ValueError

to_table must be specified for polymorphic relations

Error message

to_table must be specified for polymorphic relations (possible tables: {self._to_table_names})

What it means

Mirror of the from-table case: for a polymorphic relation target there is no single default to-table, so `declare_relation` raises ValueError listing the candidate destination tables when `to_table` is omitted.

Solutions

  1. Pass `to_table=<TableTarget>` chosen from the `(possible tables: ...)` list in the error message.
  2. If relations always target one table, declare the relation target with a single to-table so the default applies.
  3. Ensure the record object doesn't carry the table implicitly — the API requires it explicitly.

Example fix

// before
await rel_target.declare_relation(record=follow, from_table=user_table)
// after
await rel_target.declare_relation(record=follow, from_table=user_table, to_table=user_table)
Defensive patterns

Strategy: validation

Validate before calling

if to_table is None and rel_target.default_to_table is None:
    raise ValueError("declare_relation requires to_table for polymorphic relation targets")

Type guard

def can_omit_to_table(rel_target) -> bool:
    return getattr(rel_target, "_default_to_table", None) is not None

Try / catch

try:
    await rel_target.declare_relation(record=rec, from_table=src)
except ValueError as e:
    if "to_table must be specified" in str(e):
        await rel_target.declare_relation(record=rec, from_table=src, to_table=dst)
    else:
        raise

Prevention

When it happens

Trigger: Calling `declare_relation(...)` with a `from_table` (or relying on the default from-table) but without `to_table=...` when the target has multiple possible to-tables.

Common situations: Edges that may point at several node tables (User→Post, User→Comment); assuming the endpoint is inferred from the record's contents.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at python/cocoindex/connectors/surrealdb/_target.py:1217

        """Declare a relation record."""
        # Resolve from_table_name
        if from_table is not None:
            from_table_name = from_table.table_name
        elif self._default_from_table is not None:
            from_table_name = self._default_from_table
        else:
            raise ValueError(
                "from_table must be specified for polymorphic relations "
                f"(possible tables: {self._from_table_names})"
            )

        # Resolve to_table_name
        if to_table is not None:
            to_table_name = to_table.table_name
        elif self._default_to_table is not None:
            to_table_name = self._default_to_table
        else:
            raise ValueError(
                "to_table must be specified for polymorphic relations "
                f"(possible tables: {self._to_table_names})"
            )

        # Build the value dict from the record (exclude 'id' — it's the key, not content)
        if record is not None:
            if self._table_schema is not None:
                row_dict: dict[str, Any] = {}
                for col_name, col in self._table_schema.columns.items():
                    if col_name == "id":
                        continue
                    if isinstance(record, dict):
                        value = record.get(col_name)
                    else:
                        value = getattr(record, col_name)
                    if value is not None and col.encoder is not None:
                        value = col.encoder(value)
                    row_dict[col_name] = value

View on GitHub (pinned to e84aa99b32)