{"record":{"id":"9a8339af08efe8e9","repo":"openai/openai-python","slug":"pydantic-models-must-subclass-our-base-model-type","errorCode":null,"errorMessage":"Pydantic models must subclass our base model type, e.g. `from openai import BaseModel`","messagePattern":"Pydantic models must subclass our base model type, e\\.g\\. `from openai import BaseModel`","errorType":"validation","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"src/openai/_legacy_response.py","lineNumber":296,"sourceCode":"            origin  # pyright: ignore[reportUnknownArgumentType]\n        ) and issubclass(origin, response_types):\n            # Because of the invariance of our ResponseT TypeVar, users can subclass httpx.Response\n            # and pass that class to our request functions. We cannot change the variance to be either\n            # covariant or contravariant as that makes our usage of ResponseT illegal. We could construct\n            # the response class ourselves but that is something that should be supported directly in httpx\n            # as it would be easy to incorrectly construct the Response object due to the multitude of arguments.\n            if cast_to not in response_types:\n                raise ValueError(\"Subclasses of HTTP response classes cannot be passed to `cast_to`\")\n            return cast(R, response)\n\n        if (\n            inspect.isclass(\n                origin  # pyright: ignore[reportUnknownArgumentType]\n            )\n            and not issubclass(origin, BaseModel)\n            and issubclass(origin, pydantic.BaseModel)\n        ):\n            raise TypeError(\"Pydantic models must subclass our base model type, e.g. `from openai import BaseModel`\")\n\n        if (\n            cast_to is not object\n            and not origin is list\n            and not origin is dict\n            and not origin is Union\n            and not issubclass(origin, BaseModel)\n        ):\n            raise RuntimeError(\n                f\"Unsupported type, expected {cast_to} to be a subclass of {BaseModel}, {dict}, {list}, {Union}, {NoneType}, {str} or {httpx2.Response}.\"\n            )\n\n        # split is required to handle cases where additional information is included\n        # in the response, e.g. application/json; charset=utf-8\n        content_type, *_ = response.headers.get(\"content-type\", \"*\").split(\";\")\n        if not content_type.endswith(\"json\"):\n            if is_basemodel(cast_to):\n                try:","sourceCodeStart":278,"sourceCodeEnd":314,"githubUrl":"https://github.com/openai/openai-python/blob/9917c6e28e66e90e1227b3d223c06a8c5441515a/src/openai/_legacy_response.py#L278-L314","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Change your model to inherit from openai's BaseModel: from openai import BaseModel","For models you can't change, pass cast_to=dict and construct/validate your model from the dict yourself"],"exampleFix":"# before\nimport pydantic\nclass MyModel(pydantic.BaseModel):\n    id: str\n# after\nfrom openai import BaseModel\nclass MyModel(BaseModel):\n    id: str\n","handlingStrategy":"type-guard","validationCode":"from openai import BaseModel\nassert isinstance(cast_to, type) and issubclass(cast_to, BaseModel), 'use from openai import BaseModel'","typeGuard":"def is_sdk_model(t: object) -> bool:\n    from openai import BaseModel\n    return isinstance(t, type) and issubclass(t, BaseModel)","tryCatchPattern":"try:\n    resp = client.post(url, cast_to=MyModel)\nexcept TypeError as e:\n    if 'must subclass our base model' in str(e):\n        # fall back to dict parsing\n        resp = client.post(url, cast_to=dict)","preventionTips":["Standardize on `from openai import BaseModel` in all files defining response models"],"tags":["pydantic","cast-to","typing","models"],"backgroundTag":"pydantic-model-validation","analyzedSha":"9917c6e28e66e90e1227b3d223c06a8c5441515a","analyzedAt":"2026-08-28T11:46:34.183Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}