openai/openai-python · error · TypeError

Pydantic models must subclass our base model type, e.g. `fro

Error message

Pydantic models must subclass our base model type, e.g. `from openai import BaseModel`

What it means

The SDK requires Pydantic models used with cast_to to subclass the SDK's re-exported BaseModel (openai.BaseModel), which is versioned consistently with the SDK's Pydantic compatibility layer. Passing a model that subclasses pydantic.BaseModel directly mixes model hierarchies and is rejected with a TypeError.

Source

Thrown at src/openai/_legacy_response.py:296

            origin  # pyright: ignore[reportUnknownArgumentType]
        ) and issubclass(origin, response_types):
            # Because of the invariance of our ResponseT TypeVar, users can subclass httpx.Response
            # and pass that class to our request functions. We cannot change the variance to be either
            # covariant or contravariant as that makes our usage of ResponseT illegal. We could construct
            # the response class ourselves but that is something that should be supported directly in httpx
            # as it would be easy to incorrectly construct the Response object due to the multitude of arguments.
            if cast_to not in response_types:
                raise ValueError("Subclasses of HTTP response classes cannot be passed to `cast_to`")
            return cast(R, response)

        if (
            inspect.isclass(
                origin  # pyright: ignore[reportUnknownArgumentType]
            )
            and not issubclass(origin, BaseModel)
            and issubclass(origin, pydantic.BaseModel)
        ):
            raise TypeError("Pydantic models must subclass our base model type, e.g. `from openai import BaseModel`")

        if (
            cast_to is not object
            and not origin is list
            and not origin is dict
            and not origin is Union
            and not issubclass(origin, BaseModel)
        ):
            raise RuntimeError(
                f"Unsupported type, expected {cast_to} to be a subclass of {BaseModel}, {dict}, {list}, {Union}, {NoneType}, {str} or {httpx2.Response}."
            )

        # split is required to handle cases where additional information is included
        # in the response, e.g. application/json; charset=utf-8
        content_type, *_ = response.headers.get("content-type", "*").split(";")
        if not content_type.endswith("json"):
            if is_basemodel(cast_to):
                try:

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Change your model to inherit from openai's BaseModel: from openai import BaseModel
2. For models you can't change, pass cast_to=dict and construct/validate your model from the dict yourself

Example fix

# before
import pydantic
class MyModel(pydantic.BaseModel):
    id: str
# after
from openai import BaseModel
class MyModel(BaseModel):
    id: str

from openai import BaseModel
assert isinstance(cast_to, type) and issubclass(cast_to, BaseModel), 'use from openai import BaseModel'

def is_sdk_model(t: object) -> bool:
    from openai import BaseModel
    return isinstance(t, type) and issubclass(t, BaseModel)

try:
    resp = client.post(url, cast_to=MyModel)
except TypeError as e:
    if 'must subclass our base model' in str(e):
        # fall back to dict parsing
        resp = client.post(url, cast_to=dict)

When it happens

Trigger: Defining your own model as class Foo(pydantic.BaseModel) and passing cast_to=Foo to client.post/get or a typed API method; or re-exporting BaseModel from pydantic instead of from openai in shared model files.

Common situations: Copying model definitions from other projects or tutorials that import BaseModel from pydantic; code written against Pydantic v1-style models before adopting the SDK's compat layer.

Related errors

• Pydantic models must subclass our base model type, e.g. `fro
• Subclasses of HTTP response classes cannot be passed to `cas
• Unsupported type, expected {cast_to} to be a subclass of {Ba
• mode must be either 'json' or 'python'
• round_trip is only supported in Pydantic v2

AI-assisted analysis of openai/openai-python@9917c6e28e (2026-08-28). Data as JSON: /api/errors/9a8339af08efe8e9. Report an issue: GitHub.