openai/openai-python · error · TypeError

Unable to automatically parse response format type {response

Error message

Unable to automatically parse response format type {response_format}

What it means

_parse_content only knows how to parse pydantic BaseModel types and dataclass-like types (dataclass, TypedDict, NamedTuple). Any other type passed as response_format (e.g. a plain dict, int, or arbitrary class) raises this TypeError before/after the API call.

Source

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

    input_fn = cast(object, input_tool.get("function"))
    if isinstance(input_fn, PydanticFunctionTool):
        return True

    return cast(FunctionDefinition, input_fn).get("strict") or False


def _parse_content(response_format: type[ResponseFormatT], content: str) -> ResponseFormatT:
    if is_basemodel_type(response_format):
        return cast(ResponseFormatT, model_parse_json(response_format, content))

    if is_dataclass_like_type(response_format):
        if PYDANTIC_V1:
            raise TypeError(f"Non BaseModel types are only supported with Pydantic v2 - {response_format}")

        return pydantic.TypeAdapter(response_format).validate_json(content)

    raise TypeError(f"Unable to automatically parse response format type {response_format}")


def type_to_response_format_param(
    response_format: type | completion_create_params.ResponseFormat | Omit,
) -> ResponseFormatParam | Omit:
    if not is_given(response_format):
        return omit

    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

View on GitHub (pinned to 9917c6e28e)

Solutions

Use a pydantic BaseModel subclass as response_format
For simple containers, wrap them in a dataclass or BaseModel (e.g. class Output(BaseModel): items: list[int])
For raw control, use completions.create with response_format={'type':'json_object'} and parse yourself

Example fix

# before
client.chat.completions.parse(..., response_format=list[str])
# after
class Output(BaseModel):
    items: list[str]
completion = client.chat.completions.parse(..., response_format=Output)

Defensive patterns

Strategy: type-guard

Type guard

from openai._compat import is_basemodel_type
from openai.lib._parsing._completions import is_dataclass_like_type
def parseable(t: type) -> bool:
    return is_basemodel_type(t) or is_dataclass_like_type(t)

Prevention

Always model outputs as BaseModel/dataclass types
Don't pass built-in annotations like list[str] directly

When it happens

Trigger: Passing response_format=int, response_format=dict[str, int], or a non-dataclass plain class to chat.completions.parse / maybe_parse_content.

Common situations: Assuming .parse() can return arbitrary built-in types; passing an already-constructed ResponseFormat dict object instead of a class.

Related errors

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