openai/openai-python · error · TypeError

Cannot mix and match text.format with text_format

Error message

Cannot mix and match text.format with text_format

What it means

Raised by Responses.stream() when you supply both the convenience `text_format` argument and a `format` key inside the `text` dict. The SDK would not know which format definition wins, so it rejects the combination with a TypeError. `text_format` is sugar that internally sets text['format'].

Source

Thrown at src/openai/resources/responses/responses.py:1232

        if (is_given(response_id) or is_given(starting_after)) and len(new_response_args_names) > 0:
            raise ValueError(
                "Cannot provide both response_id/starting_after can't be provided together with "
                + ", ".join(new_response_args_names)
            )
        tools = _make_tools(tools)
        if len(new_response_args_names) > 0:
            if not is_given(input):
                raise ValueError("input must be provided when creating a new response")

            if not is_given(model):
                raise ValueError("model must be provided when creating a new response")

            if is_given(text_format):
                if not text:
                    text = {}

                if "format" in text:
                    raise TypeError("Cannot mix and match text.format with text_format")

                text = copy(text)
                text["format"] = _type_to_text_format_param(text_format)

            api_request: partial[Stream[ResponseStreamEvent]] = partial(
                self.create,
                input=input,
                model=model,
                tools=tools,
                context_management=context_management,
                conversation=conversation,
                include=include,
                instructions=instructions,
                max_output_tokens=max_output_tokens,
                max_tool_calls=max_tool_calls,
                metadata=metadata,
                moderation=moderation,
                parallel_tool_calls=parallel_tool_calls,

View on GitHub (pinned to 9917c6e28e)

Solutions

1. Remove `format` from the text dict and keep only text_format
2. Or drop text_format and express the format fully inside text={'format': ...}

Example fix

// before
client.responses.stream(model="gpt-4o", input="hi", text_format=MyModel, text={"format": {"type": "json_schema"}})
// after
client.responses.stream(model="gpt-4o", input="hi", text_format=MyModel)

if is_given(text_format) and text and 'format' in text:
    raise ValueError('pass either text_format or text["format"], not both')
# then call client.responses.stream(..., text_format=text_format, text=text)

def clean_text_arg(text: dict | None, text_format) -> dict | None:
    if text_format is not None and text:
        text = {k: v for k, v in text.items() if k != 'format'}
    return text

try:
    client.responses.stream(model=m, input=i, text_format=tf, text=text)
except TypeError as e:
    if 'text.format' in str(e):
        text.pop('format', None)
        client.responses.stream(model=m, input=i, text_format=tf, text=text)
    else:
        raise

When it happens

Trigger: client.responses.stream(model=..., input=..., text_format=MyModel, text={'format': {...}}). Only checked when is_given(text_format) and 'format' in text.

Common situations: Upgrading from an older pattern where you constructed text={'format': {...}} manually and then adopting the typed text_format helper without removing the old key; merging code samples that use both styles.

Related errors

• model must be provided when creating a new response
• id must be provided when streaming an existing response
• response_id must be provided when streaming an existing resp
• Didn't receive a `response.completed` event.
• Expected a non-empty value for `response_id` but received {r

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