openai/openai-python · error · RuntimeError

Unsupported type, expected {cast_to} to be a subclass of {Ba

Error message

Unsupported type, expected {cast_to} to be a subclass of {BaseModel}, {dict}, {list}, {Union}, {NoneType}, {str} or {httpx2.Response}.

What it means

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.

Source

Thrown at src/openai/_response.py:238

            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(type, cast_to)):
                try:
                    data = response.json()
                except Exception as exc:
                    log.debug("Could not read JSON from response data due to %s", type(exc).__name__)
                else:
                    return self._client._process_response_data(
                        data=data,
                        cast_to=cast_to,  # type: ignore
                        response=response,
                    )

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Use a Pydantic model subclassing openai.BaseModel for structured data
2. Use cast_to=dict or cast_to=str for untyped payloads
3. Use cast_to=object to get the raw parsed JSON

Example fix

// before
from dataclasses import dataclass
@dataclass
class Job:
    id: str
resp = client.jobs.create(..., cast_to=Job)  # unsupported

// after
from openai import BaseModel
class Job(BaseModel):
    id: str
resp = client.jobs.create(..., cast_to=Job)

from openai import BaseModel
import httpx, typing

SUPPORTED = (str, dict, list, object, httpx.Response)
def cast_to_supported(cast_to) -> bool:
    if isinstance(cast_to, type):
        return issubclass(cast_to, (BaseModel, str, dict, list, httpx.Response))
    origin = typing.get_origin(cast_to)
    return origin in (list, dict, typing.Union) or cast_to is None or cast_to is object

def is_supported_cast_to(cast_to) -> bool:
    from openai import BaseModel
    import httpx, typing
    if cast_to in (object, None):
        return True
    origin = typing.get_origin(cast_to) or cast_to
    if isinstance(origin, type):
        return issubclass(origin, BaseModel) or origin in (list, dict, str, httpx.Response, object)
    return origin is typing.Union

try:
    result = client.get(..., cast_to=Target)
except RuntimeError as e:
    if 'Unsupported type' in str(e):
        result = client.get(..., cast_to=dict)

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Subclasses of HTTP response classes cannot be passed to `cas
• Subclasses of HTTP response classes cannot be passed to `cas
• Pydantic models must subclass our base model type, e.g. `fro
• Unsupported type, expected {cast_to} to be a subclass of {Ba
• Pydantic models must subclass our base model type, e.g. `fro

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