cocoindex-io/cocoindex · error · TypeError

record_type must be a record type (dataclass, NamedTuple, Py

Error message

record_type must be a record type (dataclass, NamedTuple, Pydantic model), got {type(record_type)}

What it means

`TableSchema.from_class` introspects the given type to derive columns; it only supports record types (dataclass, NamedTuple, Pydantic model) via `is_record_type`. Passing any other type (plain class, dict, typing construct) raises TypeError because there is no field metadata to introspect.

Source

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

        self.row_type = row_type

    @property
    def value_field_names(self) -> list[str]:
        """Column names other than the primary key, in declared order."""
        return [c for c in self.columns if c != self.primary_key]

    @classmethod
    async def from_class(
        cls,
        record_type: type[RowT],
        *,
        primary_key: str = "id",
        column_overrides: dict[str, FalkorType | res_schema.VectorSchemaProvider]
        | None = None,
    ) -> "TableSchema[RowT]":
        """Build a TableSchema by introspecting a dataclass / NamedTuple / Pydantic model."""
        if not is_record_type(record_type):
            raise TypeError(
                f"record_type must be a record type (dataclass, NamedTuple, "
                f"Pydantic model), got {type(record_type)}"
            )
        columns = await cls._columns_from_record_type(record_type, column_overrides)
        return cls(columns, primary_key=primary_key, row_type=record_type)

    @staticmethod
    async def _columns_from_record_type(
        record_type: type,
        column_overrides: dict[str, FalkorType | res_schema.VectorSchemaProvider]
        | None,
    ) -> dict[str, ColumnDef]:
        record_info = RecordType(record_type)
        columns: dict[str, ColumnDef] = {}

        for field in record_info.fields:
            type_info = analyze_type_info(field.type_hint)

View on GitHub (pinned to e84aa99b32)

Solutions

1. Pass the class itself, not an instance: `from_class(Row, ...)` not `from_class(row, ...)`.
2. Convert the row type to a `@dataclass`, `NamedTuple`, or Pydantic `BaseModel`.
3. If the type is a TypedDict, migrate it to a dataclass since TypedDict is not supported here.

Example fix

// before
schema = await falkordb.TableSchema.from_class(row_instance)
// after
@dataclasses.dataclass
class Row: id: str; text: str
schema = await falkordb.TableSchema.from_class(Row, primary_key="id")

import dataclasses, typing
if not (dataclasses.is_dataclass(Row) or issubclass(Row, tuple) or issubclass(Row, BaseModel)):
    raise TypeError("from_class needs a dataclass / NamedTuple / Pydantic model class")

def is_record_type(t: object) -> bool:
    import dataclasses
    return dataclasses.is_dataclass(t) or (isinstance(t, type) and issubclass(t, tuple)) or (isinstance(t, type) and issubclass(t, BaseModel))

try:
    schema = await falkordb.TableSchema.from_class(Row)
except TypeError as e:
    if "must be a record type" in str(e):
        logging.error("Pass the class, not an instance; use @dataclass/NamedTuple/Pydantic: %s", e)
    raise

When it happens

Trigger: Calling `await TableSchema.from_class(dict)` or `from_class(SomePlainClass)` or passing an instance instead of the class; also passing generic aliases like `list[Row]`.

Common situations: Passing an instantiated dataclass object rather than the class; using a TypedDict or plain dict as the row type; refactoring away from dataclass without updating from_class calls.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• record_type must be a record type (dataclass, NamedTuple, Py
• record_type must be a record type (dataclass, NamedTuple, Py
• record_type must be a record type (dataclass, NamedTuple, Py
• Unsupported record type: {self.record_type}
• timeout() requires a datetime.timedelta

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