Problem with the metadata field (NameError: Field name "metadata" shadows a BaseModel attribute; use a different field name with "alias='metadata'".) · Issue #290 · fastapi/sqlmodel · GitHub

First Check

I added a very descriptive title to this issue.
I used the GitHub search to find a similar issue 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

# database.py

from sqlmodel import Session, create_engine
from core.settings import settings


engine = create_engine(settings.SQLALCHEMY_DATABASE_URL, echo=True)

def get_session():
    with Session(engine) as session:
        yield session


# models.py

from typing import Optional

from sqlmodel import Field, SQLModel


class Companies(SQLModel, table=True):
    avatar: Optional[str] = None
    business_name: Optional[str] = None
    country_id: int = Field(index=True)
    created: str
    crm_id: Optional[str] = None
    id: Optional[str] = Field(default=None, primary_key=True)
    is_active: bool
    is_removed: bool
    metadata_: Optional[str] = Field(default=None, alias="metadata")  # Error: Companies.metadata_ does not exist
    
    # before
    metadata: Optional[str] = Field(default=None)  # Error: NameError

Description

I created a model but this have a field named metadata, is an existing database, so I can't change the fields names, since the SQLModel class also has a field called metadata, when I run the app I get the following error
NameError: Field name "metadata" shadows a BaseModel attribute; use a different field name with "alias='metadata'".

I used the Field class of sqlmodel and assigned the alias but it does not work.
metadata_: Optional[str] = Field(default=None, alias="metadata")
With this the error is that Table.metadata_ field does not exist

Is there any way to create an tabla with the metadata field without giving problems with SQLModel?

Operating System

Linux

Operating System Details

No response

SQLModel Version

0.0.6

Python Version

Python 3.9.5

Additional Context

No response

I have found the solution using the sa_column argument for the Field class, but the alias argument in the SQLModel class should work.
example code.
metadata_: Optional[str] = Field(sa_column=Column("metadata", String, default=None))

Would this problem be fixed? Do we have any walkaround for metadata's validation/serialization currently?

Would this problem be fixed? Do we have any walkaround for metadata's validation/serialization currently?

Some research

from pydantic import BaseModel
from pydantic import Field as PydanticField
from sqlmodel import Field, SQLModel


class PydanticModelWithPydanticField(BaseModel):
    metadata_: str = PydanticField(alias="metadata")


class PydanticModelWithSQLModelField(BaseModel):
    metadata_: str = Field(alias="metadata")


class SQLModelWithPydanticField(SQLModel):
    metadata_: str = PydanticField(alias="metadata")


class SQLModelWithSQLModelField(SQLModel):
    metadata_: str = Field(alias="metadata")


if __name__ == "__main__":
    try:
        sql_model_no_suffix = SQLModelWithSQLModelField(metadata="metadata")
        print(f'{sql_model_no_suffix.model_dump(by_alias=False)=}')
        print(f'{sql_model_no_suffix.model_dump(by_alias=True)=}')
    except Exception as e:
        print(f'{e=}')

    sql_model_with_suffix = SQLModelWithSQLModelField(metadata_="metadata")
    print(f'{sql_model_with_suffix.model_dump(by_alias=False)=}')
    print(f'{sql_model_with_suffix.model_dump(by_alias=True)=}')

    sql_model_with_pydantic_field = SQLModelWithPydanticField(metadata="metadata")
    print(f'{sql_model_with_pydantic_field.model_dump(by_alias=False)=}')
    print(f'{sql_model_with_pydantic_field.model_dump(by_alias=True)=}')

    try:
        sql_model_with_pydantic_field_with_suffix = SQLModelWithPydanticField(metadata_="metadata")
        print(f'{sql_model_with_pydantic_field_with_suffix.model_dump(by_alias=False)=}')
        print(f'{sql_model_with_pydantic_field_with_suffix.model_dump(by_alias=True)=}')
    except Exception as e:
        print(f'{e=}')

    pydantic_model_with_pydantic_field = PydanticModelWithPydanticField(metadata="metadata")
    print(f'{pydantic_model_with_pydantic_field.model_dump(by_alias=False)=}')
    print(f'{pydantic_model_with_pydantic_field.model_dump(by_alias=True)=}')

    try:
        pydantic_model_with_pydantic_field_with_suffix = PydanticModelWithPydanticField(metadata_="metadata")
        print(f'{pydantic_model_with_pydantic_field_with_suffix.model_dump(by_alias=False)=}')
        print(f'{pydantic_model_with_pydantic_field_with_suffix.model_dump(by_alias=True)=}')
    except Exception as e:
        print(f'{e=}')

    try:
        pydantic_model_no_suffix = PydanticModelWithSQLModelField(metadata="metadata")
        print(f'{pydantic_model_no_suffix.model_dump(by_alias=False)=}')
        print(f'{pydantic_model_no_suffix.model_dump(by_alias=True)=}')
    except Exception as e:
        print(f'{e=}')

    pydantic_model_with_sql_model_field_with_suffix = PydanticModelWithSQLModelField(metadata_="metadata")
    print(f'{pydantic_model_with_sql_model_field_with_suffix.model_dump(by_alias=False)=}')
    print(f'{pydantic_model_with_sql_model_field_with_suffix.model_dump(by_alias=True)=}')

output of previous code

e=1 validation error for SQLModelWithSQLModelField
metadata_
  Field required [type=missing, input_value={'metadata': 'metadata'}, input_type=dict]
    For further information visit https://errors.pydantic.dev/2.8/v/missing
sql_model_with_suffix.model_dump(by_alias=False)={'metadata_': 'metadata'}
sql_model_with_suffix.model_dump(by_alias=True)={'metadata_': 'metadata'}
sql_model_with_pydantic_field.model_dump(by_alias=False)={'metadata_': 'metadata'}
sql_model_with_pydantic_field.model_dump(by_alias=True)={'metadata': 'metadata'}
e=1 validation error for SQLModelWithPydanticField
metadata
  Field required [type=missing, input_value={'metadata_': 'metadata'}, input_type=dict]
    For further information visit https://errors.pydantic.dev/2.8/v/missing
pydantic_model_with_pydantic_field.model_dump(by_alias=False)={'metadata_': 'metadata'}
pydantic_model_with_pydantic_field.model_dump(by_alias=True)={'metadata': 'metadata'}
e=1 validation error for PydanticModelWithPydanticField
metadata
  Field required [type=missing, input_value={'metadata_': 'metadata'}, input_type=dict]
    For further information visit https://errors.pydantic.dev/2.8/v/missing
e=1 validation error for PydanticModelWithSQLModelField
metadata_
  Field required [type=missing, input_value={'metadata': 'metadata'}, input_type=dict]
    For further information visit https://errors.pydantic.dev/2.8/v/missing
pydantic_model_with_sql_model_field_with_suffix.model_dump(by_alias=False)={'metadata_': 'metadata'}
pydantic_model_with_sql_model_field_with_suffix.model_dump(by_alias=True)={'metadata_': 'metadata'}

Current walk around

Define a new response model inheirt from pydantic.BaseModel instead of SQLModel for fastapi.

conclusion

This problem seems come from SQLModel's Field

the serialization_alias needs to be set for the FieldInfo. This can be done through the schema_extra argument

metadata_: dict = Field(sa_column=Column("metadata", JSON, nullable=False), default_factory=dict, schema_extra={'serialization_alias': 'metadata'})

So, current solution is to use Field(sa_column=Column("metadata", ...).

I personally think it would be good to use alias parameter as a default value for column name.
I just created an issue to track problems with alias parameter and mentioned this idea there.

I'll close this issue now and let's track all alias-related things in that new issue

Problem with the metadata field (NameError: Field name "metadata" shadows a BaseModel attribute; use a different field name with "alias='metadata'".) · Issue #290 · fastapi/sqlmodel · GitHub

Repository navigation

Problem with the metadata field (NameError: Field name "metadata" shadows a BaseModel attribute; use a different field name with "alias='metadata'".) #290

First Check

Commit to Help

Example Code

Description

Operating System

Operating System Details

SQLModel Version

Python Version

Additional Context

Some research

Current walk around

conclusion

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Problem with the metadata field (NameError: Field name "metadata" shadows a BaseModel attribute; use a different field name with "alias='metadata'".) · Issue #290 · fastapi/sqlmodel · GitHub

Repository navigation

Problem with the metadata field (NameError: Field name "metadata" shadows a BaseModel attribute; use a different field name with "alias='metadata'".) #290

Description

First Check

Commit to Help

Example Code

Description

Operating System

Operating System Details

SQLModel Version

Python Version

Additional Context

Activity

MichaelLan commented on Mar 29, 2022

tcztzy commented on Aug 1, 2024

tcztzy commented on Aug 1, 2024

Some research

Current walk around

conclusion

IEH-intekglobal commented on Jan 22, 2025

YuriiMotov commented on Aug 26, 2025

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions