Fix FastAPI Pydantic Error: orm_mode Must Be Enabled (2026)

The orm_mode must be enabled in Pydantic models when you’re trying to use them to represent ORM objects directly, and the error means your Pydantic model is configured to expect ORM integration but the ORM itself isn’t set up to be compatible.

Here’s what’s actually broken: Your Pydantic BaseModel is set up with Config.orm_mode = True, which tells Pydantic to treat incoming data as if it were an ORM instance (allowing you to access fields like obj.field instead of obj['field']). However, the object you’re passing into the Pydantic model for validation or serialization is not structured in a way that Pydantic can introspect like an ORM object. This usually happens when you forget to enable orm_mode on the Pydantic model itself, or when the ORM object you’re using isn’t actually an ORM object at all.

Here are the common causes and how to fix them:

1. orm_mode is not enabled on your Pydantic model. This is the most frequent culprit. You’ve defined a Pydantic model that intends to work with ORM objects, but you forgot to tell Pydantic to enable that specific mode.

Diagnosis: Look at your Pydantic model definition. Does it have a nested Config class with orm_mode = True?

Fix: Add or ensure the Config class with orm_mode = True is present.

from pydantic import BaseModel

class User(BaseModel):
    id: int
    name: str

    class Config:
        orm_mode = True # This is the crucial line

Why it works: This explicitly tells Pydantic to use its ORM mode, allowing it to access attributes of the input object using dot notation (e.g., user_instance.id) instead of dictionary-style access.

2. You are passing a plain dictionary or a non-ORM object to the Pydantic model. Even with orm_mode = True, if you pass a standard Python dictionary or a custom object that doesn’t have attributes Pydantic can introspect, you’ll still get issues. Pydantic expects something it can treat like an ORM object.

Diagnosis: Check the type of the object you are passing to your Pydantic model’s constructor. Use type(your_object). If it’s dict or a custom class without attributes, this is the problem.

Fix: If you have a dictionary, you can either:

Instantiate the Pydantic model directly with the dictionary (without orm_mode enabled, or using model_validate in Pydantic v2).
If you must use orm_mode, create a simple object that mimics an ORM object.

Example for dictionaries (Pydantic v2):

from pydantic import BaseModel
from typing import Any

class Item(BaseModel):
    name: str
    description: str | None = None

    class Config:
        orm_mode = True # This is still useful for actual ORM objects

data = {"name": "Foo", "description": "A Bar"}
item = Item.model_validate(data) # Use model_validate for dictionaries

Example for a custom object:

class MockORM:
    def __init__(self, id, name):
        self.id = id
        self.name = name

mock_obj = MockORM(id=1, name="Test")

class User(BaseModel):
    id: int
    name: str

    class Config:
        orm_mode = True

user = User.model_validate(mock_obj) # Now this works

Why it works: model_validate (Pydantic v2) is designed to handle various input types gracefully. For orm_mode, providing an object with attributes that Pydantic can access via getattr() is key.

3. Using Pydantic v1 orm_mode with a Pydantic v2 model_validate incompatibility. If you’re migrating from Pydantic v1 to v2, the way orm_mode is handled has changed. In v2, orm_mode is still supported for backward compatibility, but the primary way to validate data is often model_validate. If you’re mixing old patterns with new ones or expecting v1 behavior in a v2 context without proper migration, you might see this error.

Diagnosis: Check your Pydantic version (pip show pydantic). If it’s v2, and you’re still seeing orm_mode errors, you might be using deprecated patterns.

Fix: For Pydantic v2, while orm_mode = True still works, it’s often recommended to use model_validate which is more flexible. If you’re loading from an ORM, model_validate can often infer the correct behavior. If you must use orm_mode explicitly, ensure your model configuration is correct for v2.

# Pydantic v2
from pydantic import BaseModel

class User(BaseModel):
    id: int
    name: str

    class Config:
        orm_mode = True # Still valid for compatibility

# Example usage with an ORM object (e.g., SQLAlchemy)
# Assuming `orm_user` is an SQLAlchemy user instance
# user_schema = User.model_validate(orm_user) # This is the preferred v2 way
# or if sticking to orm_mode:
# user_schema = User.from_orm(orm_user) # This is the v1 way, still works for compatibility in v2

Why it works: model_validate in Pydantic v2 is the modern, flexible approach for data parsing and validation, handling ORM objects, dictionaries, and other types more robustly than older methods. from_orm is kept for backward compatibility.

4. The ORM object you’re using doesn’t expose attributes correctly. Sometimes, the ORM object itself might be misconfigured or not fully initialized, leading Pydantic to believe it can’t access the necessary attributes. This is less common with standard ORMs like SQLAlchemy or Django, but can occur with custom ORMs or complex setups.

Diagnosis: Inspect the ORM object directly. Try accessing its attributes in a Python interpreter: your_orm_object.attribute_name. If this fails, the ORM object is the problem, not Pydantic.
Fix: Ensure your ORM object is properly instantiated and its attributes are accessible. This might involve session commits, proper model definitions in your ORM, or ensuring lazy-loaded attributes are loaded before Pydantic tries to access them.
Why it works: Pydantic’s orm_mode relies on Python’s introspection capabilities (getattr) to read attributes from the provided object. If the object doesn’t have these attributes or they aren’t accessible, Pydantic cannot proceed.

5. You are trying to use orm_mode with a Pydantic model that is not intended for ORM objects. This is a conceptual error. If your Pydantic model is designed to parse incoming JSON or other data structures, and you’re not passing ORM objects to it, then orm_mode = True is actively harmful and will cause this error because Pydantic will try to introspect the data as if it were an ORM.

Diagnosis: Review the purpose of your Pydantic model. Is it meant to represent an ORM entity, or is it for request/response data? If the latter, orm_mode should not be enabled.

Fix: Remove the Config.orm_mode = True line from your Pydantic model.

from pydantic import BaseModel

class UserCreateSchema(BaseModel): # Not for ORM, but for creating a user
    username: str
    email: str

    # NO Config class with orm_mode = True needed here

Why it works: By removing orm_mode = True, the Pydantic model reverts to its default behavior, which is to parse data from dictionaries or other standard Python structures, matching the expected input for non-ORM use cases.

After fixing these, the next error you’ll likely encounter is if your Pydantic model’s fields don’t match the fields available on your ORM object, or if there are type mismatches that Pydantic’s validation cannot resolve.