Cannot use a relationship field named 'items'

[Shavinder]

First Check

• I added a very descriptive title here.
• I used the GitHub search to find a similar question and didn't find it.
• I searched the SQLModel documentation, with the integrated search.
• I already searched in Google "How to X in SQLModel" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to SQLModel but to Pydantic.
• I already checked if it is not related to SQLModel but to SQLAlchemy.

Commit to Help

• I commit to help with one of those options 👆

Example Code

from typing import Optional
from sqlmodel import SQLModel, Field, Relationship   

class Invoice(SQLModel, table=True):
    __tablename__ = "invoices"
    customer: str
    id: Optional[int] = Field(default=None, primary_key=True)
    # relationship
    items: Optional[list["Item"]] = Relationship(back_populates="invoice")
    # itemsx: Optional[list["Item"]] = Relationship(back_populates="invoice")

class Item(SQLModel, table=True):
    __tablename__ = "items"
    name: str
    id: Optional[int] = Field(default=None, primary_key=True)
    school_id: int = Field(default=None, foreign_key="invoices.id")
    # relationship
    invoice: "Invoice" = Relationship(back_populates="items")
    # invoice: "Invoice" = Relationship(back_populates="itemsx")

inv=Invoice.model_validate({'customer':'ABC'})

Description

On running this code:
inv=Invoice.model_validate({'customer':'ABC'})

I get this error:
TypeError: Incompatible collection type: builtin_function_or_method is not list-like

Operating System

Windows

Operating System Details

No response

SQLModel Version

0.0.19

Python Version

3.12.0

Additional Context

No response

[GLec1er]

items is not inherently forbidden as a relationship name. In SQLModel 0.0.19, this case collides with dict.items during model_validate().

After validating the fields, sqlmodel_validate in 0.0.19 reads each relationship with getattr(use_obj, key, Undefined). For your dictionary and the key "items", that returns the dictionary's bound items() method. Assigning that method to a list relationship produces the reported error.

For the input in your example, validate a separate input model first, then construct the table object from the validated fields:

class InvoiceCreate(SQLModel):  # no table=True or relationships
    customer: str

payload = InvoiceCreate.model_validate({"customer": "ABC"})
inv = Invoice(**payload.model_dump())

assert inv.customer == "ABC"
assert inv.items == []

Keep your existing Invoice / Item definitions and back_populates="items". This avoids renaming the relationship and retains input validation; simply switching to Invoice(**raw_data) would not provide the same validation guarantee for a table model.

I reproduced the original exception with SQLModel 0.0.19, Pydantic 2.8.2 and SQLAlchemy 2.0.55. The input-model version rejects an invalid customer, and a SQLite insert/reload with an attached Item preserves the items relationship and its back reference. This example handles the flat input shown in the question; nested item creation would need its own input model and explicit conversion.

The separate data/table model pattern is also covered in the SQLModel tutorial.

Prepared with AI assistance; reproduction, validation and SQLite persistence checked locally.