{"record":{"id":"994ad1a291b06376","repo":"openai/openai-python","slug":"unsupported-type-expected-cast-to-to-be-a-subcl-994ad1","errorCode":null,"errorMessage":"Unsupported type, expected {cast_to} to be a subclass of {BaseModel}, {dict}, {list}, {Union}, {NoneType}, {str} or {httpx2.Response}.","messagePattern":"Unsupported type, expected (.+?) to be a subclass of (.+?), (.+?), (.+?), (.+?), (.+?), (.+?) or (.+?)\\.","errorType":"validation","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/openai/_response.py","lineNumber":238,"sourceCode":"            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:\n                    data = response.json()\n                except Exception as exc:\n                    log.debug(\"Could not read JSON from response data due to %s\", type(exc).__name__)\n                else:\n                    return self._client._process_response_data(\n                        data=data,\n                        cast_to=cast_to,  # type: ignore\n                        response=response,\n                    )","sourceCodeStart":220,"sourceCodeEnd":256,"githubUrl":"https://github.com/openai/openai-python/blob/9917c6e28e66e90e1227b3d223c06a8c5441515a/src/openai/_response.py#L220-L256","documentation":"The response parser only supports a fixed set of cast_to target types: subclasses of openai.BaseModel, dict, list, Union, None, str, and httpx.Response. Passing anything else (a dataclass, a primitive type, an arbitrary class, a tuple) raises this RuntimeError.","triggerScenarios":"Calling an API method with cast_to=SomeDataclass, cast_to=int, cast_to=MyPlainClass, or a typing construct like Tuple[...] — none of which are in the supported set.","commonSituations":"Assuming the parser works like a general deserializer (e.g. msgspec or dacite) and passing dataclasses or primitives; migrating code from other SDKs that accept arbitrary types.","solutions":["Use a Pydantic model subclassing openai.BaseModel for structured data","Use cast_to=dict or cast_to=str for untyped payloads","Use cast_to=object to get the raw parsed JSON"],"exampleFix":"// before\nfrom dataclasses import dataclass\n@dataclass\nclass Job:\n    id: str\nresp = client.jobs.create(..., cast_to=Job)  # unsupported\n\n// after\nfrom openai import BaseModel\nclass Job(BaseModel):\n    id: str\nresp = client.jobs.create(..., cast_to=Job)","handlingStrategy":"validation","validationCode":"from openai import BaseModel\nimport httpx, typing\n\nSUPPORTED = (str, dict, list, object, httpx.Response)\ndef cast_to_supported(cast_to) -> bool:\n    if isinstance(cast_to, type):\n        return issubclass(cast_to, (BaseModel, str, dict, list, httpx.Response))\n    origin = typing.get_origin(cast_to)\n    return origin in (list, dict, typing.Union) or cast_to is None or cast_to is object","typeGuard":"def is_supported_cast_to(cast_to) -> bool:\n    from openai import BaseModel\n    import httpx, typing\n    if cast_to in (object, None):\n        return True\n    origin = typing.get_origin(cast_to) or cast_to\n    if isinstance(origin, type):\n        return issubclass(origin, BaseModel) or origin in (list, dict, str, httpx.Response, object)\n    return origin is typing.Union","tryCatchPattern":"try:\n    result = client.get(..., cast_to=Target)\nexcept RuntimeError as e:\n    if 'Unsupported type' in str(e):\n        result = client.get(..., cast_to=dict)","preventionTips":["Restrict cast_to to BaseModel subclasses or dict/list/str/object/httpx.Response","Don't pass dataclasses or primitives"],"tags":["cast-to","typing","response-parsing"],"backgroundTag":"unsupported-cast-to-type","analyzedSha":"9917c6e28e66e90e1227b3d223c06a8c5441515a","analyzedAt":"2026-08-28T11:46:34.183Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}