{"record":{"id":"203f54a0d6b096b6","repo":"openai/openai-python","slug":"pydantic-models-must-subclass-our-base-model-type-203f54","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/_response.py","lineNumber":229,"sourceCode":"        response_types = http_response_types()\n        if inspect.isclass(origin) 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(type, cast_to)):\n                try:","sourceCodeStart":211,"sourceCodeEnd":247,"githubUrl":"https://github.com/openai/openai-python/blob/9917c6e28e66e90e1227b3d223c06a8c5441515a/src/openai/_response.py#L211-L247","documentation":"The SDK requires Pydantic models passed via `cast_to` to subclass its own re-exported BaseModel (from openai import BaseModel), not a directly imported pydantic.BaseModel. The SDK's BaseModel carries extra pydantic config the parser relies on, so foreign pydantic models are rejected with a TypeError.","triggerScenarios":"Calling client.post(..., cast_to=MyModel) or a typed API method where MyModel subclasses pydantic.BaseModel directly (or a BaseModel from another library version) instead of openai.BaseModel.","commonSituations":"Copying model definitions from pydantic tutorials, sharing model classes between an app and the SDK, or pydantic v1/v2 import mismatches where the model resolves to plain pydantic.BaseModel.","solutions":["Change the model's base class: `from openai import BaseModel` and subclass that","If using generated models, regenerate or ensure they import BaseModel from the openai package","For arbitrary dict-like data, use cast_to=dict or object instead of a pydantic model"],"exampleFix":"// before\nimport pydantic\nclass MyModel(pydantic.BaseModel):\n    id: str\n\n// after\nfrom openai import BaseModel\nclass MyModel(BaseModel):\n    id: str","handlingStrategy":"validation","validationCode":"from openai import BaseModel as OpenAIBaseModel\nimport pydantic\n\ndef validate_model(model: type) -> None:\n    if issubclass(model, pydantic.BaseModel) and not issubclass(model, OpenAIBaseModel):\n        raise TypeError(f\"{model.__name__} must subclass openai.BaseModel\")","typeGuard":"def uses_openai_base_model(model: type) -> bool:\n    from openai import BaseModel\n    return isinstance(model, type) and issubclass(model, BaseModel)","tryCatchPattern":"try:\n    result = client.post(..., cast_to=MyModel)\nexcept TypeError as e:\n    if 'base model' in str(e):\n        # switch base class and retry\n        ...","preventionTips":["Standardize on `from openai import BaseModel` in all model files","Lint against direct pydantic.BaseModel imports in SDK call sites"],"tags":["pydantic","cast-to","typing","base-model"],"backgroundTag":"wrong-pydantic-base-model","analyzedSha":"9917c6e28e66e90e1227b3d223c06a8c5441515a","analyzedAt":"2026-08-28T11:46:34.183Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}