openai/openai-python · error · TypeError

Unsupported response_format type - {response_format}

Error message

Unsupported response_format type - {response_format}

What it means

type_to_response_format_param converts a Python type into a json_schema response_format param for the API. It only supports pydantic BaseModel subclasses and dataclass-like types; anything else (built-ins, arbitrary classes, enums at top level) is unsupported.

Source

Thrown at src/openai/lib/_parsing/_completions.py:279

    if is_response_format_param(response_format):
        return response_format

    # type checkers don't narrow the negation of a `TypeGuard` as it isn't
    # a safe default behaviour but we know that at this point the `response_format`
    # can only be a `type`
    response_format = cast(type, response_format)

    json_schema_type: type[pydantic.BaseModel] | pydantic.TypeAdapter[Any] | None = None

    if is_basemodel_type(response_format):
        name = response_format.__name__
        json_schema_type = response_format
    elif is_dataclass_like_type(response_format):
        name = response_format.__name__
        json_schema_type = pydantic.TypeAdapter(response_format)
    else:
        raise TypeError(f"Unsupported response_format type - {response_format}")

    return {
        "type": "json_schema",
        "json_schema": {
            "schema": to_strict_json_schema(json_schema_type),
            "name": name,
            "strict": True,
        },
    }

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Define the output as a pydantic BaseModel or dataclass
2. If you already have a JSON schema, pass response_format={'type':'json_schema','json_schema':{...}} directly instead of a Python type

Example fix

# before
class Output: ...  # plain class
# after
from pydantic import BaseModel
class Output(BaseModel): ...

def usable_format(t: object) -> bool:
    return inspect.isclass(t) and (issubclass(t, pydantic.BaseModel) or dataclasses.is_dataclass(t))

When it happens

Trigger: Passing a plain class, dict type, or primitive annotation where a response format type is expected in .parse() flows that build the API request schema.

Common situations: Passing an instance instead of the class; using non-Pydantic ORMs or attrs classes as output models.

Related errors

• Unable to automatically parse response format type {response
• Unable to automatically parse response format type {text_for
• invalid datetime format
• invalid date format
• Currently only `function` tool types support auto-parsing; R

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