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

This TypeError is raised by TableSchema.from_class when the record_type argument is not a supported record type — i.e. not a dataclass, NamedTuple, or Pydantic model, as determined by is_record_type. from_class builds the schema by introspecting the type's fields, which is only possible for those structures. The message includes the actual type received.

Source

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

        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, Neo4jType | 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, Neo4jType | 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)

            all_annotations: list[Any] = []

View on GitHub (pinned to e84aa99b32)

Solutions

Annotate the type as a @dataclass, typing.NamedTuple, or Pydantic BaseModel.
Pass the class itself, not an instance: from_class(MyRecord) not from_class(MyRecord()).
Check is_record_type to see exactly which types are accepted.

Example fix

// before
class Doc:
    id: str
    embedding: list[float]
TableSchema.from_class(Doc)
// after
@dataclass
class Doc:
    id: str
    embedding: list[float]
TableSchema.from_class(Doc)

Defensive patterns

Strategy: type-guard

Validate before calling

import dataclasses, typing
from pydantic import BaseModel
assert dataclasses.is_dataclass(Record) or issubclass(Record, tuple) or issubclass(Record, BaseModel), "pass a dataclass/NamedTuple/Pydantic model"
TableSchema.from_class(Record)

Type guard

from typing import TypeGuard, Any
import dataclasses
from pydantic import BaseModel
def is_record(t: Any) -> TypeGuard[type]:
    return dataclasses.is_dataclass(t) or (isinstance(t, type) and issubclass(t, (tuple, BaseModel)))

Try / catch

try:
    schema = await TableSchema.from_class(Record)
except TypeError as e:
    raise TypeError("from_class needs a dataclass, NamedTuple, or Pydantic model class") from e

Prevention

Define row records as @dataclass / NamedTuple / BaseModel, never TypedDict or plain classes
Pass the class, not an instance, to from_class
Add a type annotation: def build(rt: type[MyRecord]) so type checkers catch mistakes

When it happens

Trigger: Calling TableSchema.from_class with a plain class, a TypedDict, a dict, a NamedTuple-like but unregistered type, or an instance instead of the class — e.g. from_class(dict) or from_class(SomePlainClass).

Common situations: Using TypedDict (not supported by is_record_type) instead of dataclass/NamedTuple/Pydantic; forgetting the @dataclass decorator; accidentally passing an instantiated object rather than the type.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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