Repository navigation
Response.output_text and responses.parse fail when an output_text item has text: null #3063
Description
Confirm this is an issue with the Python library and not an underlying OpenAI API
- This is an issue with the Python library
Describe the bug
Response.output_text can fail when a Responses API payload includes an output_text content item whose text field is null.
There are two affected layers:
- strict response parsing rejects
ResponseOutputText.text = null - parsed responses can still attempt structured parsing on an
output_textitem whosetextisnull
Expected behavior:
- the SDK should accept nullable
output_text.textvalues from the API Response.output_textshould ignore null entries instead of failingresponses.parse(...)should skip structured parsing for nulloutput_textitems
Related PR: #3062
To Reproduce
Create or receive a Responses API payload where a message contains an output_text item with text: null, for example alongside another normal output_text item.
Code snippets
from openai.types.responses.response import Response
data = {
"id": "resp_null_output_text",
"object": "response",
"created_at": 0,
"status": "completed",
"background": False,
"error": None,
"incomplete_details": None,
"instructions": None,
"max_output_tokens": None,
"max_tool_calls": None,
"model": "gpt-4o-mini",
"output": [
{
"id": "msg_null_output_text",
"type": "message",
"status": "completed",
"role": "assistant",
"content": [
{
"type": "output_text",
"annotations": [],
"logprobs": [],
"text": None,
},
{
"type": "output_text",
"annotations": [],
"logprobs": [],
"text": '{"message":"hello"}',
},
],
}
],
"parallel_tool_calls": True,
"previous_response_id": None,
"prompt_cache_key": None,
"reasoning": {"effort": None, "summary": None},
"safety_identifier": None,
"service_tier": "default",
"store": True,
"temperature": 1.0,
"text": {"format": {"type": "text"}, "verbosity": "medium"},
"tool_choice": "auto",
"tools": [],
"top_logprobs": 0,
"top_p": 1.0,
"truncation": "disabled",
"usage": {
"input_tokens": 1,
"input_tokens_details": {"cached_tokens": 0},
"output_tokens": 1,
"output_tokens_details": {"reasoning_tokens": 0},
"total_tokens": 2,
},
"user": None,
"metadata": {},
}
Response.model_validate(data)OS
Windows 11
Python version
Python 3.13.12
Library version
openai v2.30.0
Activity
nightcityblade commentedon Apr 23, 2026
Hi, I'd like to work on this. I'll submit a PR shortly.
Xsidz commentedon Aug 16, 2026
Working on this in PR #3632 (layer 1: ResponseOutputText.text nullable) and PR #3628 (layer 2: output_text property guard).
dajiaohuang commentedon Sep 25, 2026
Proposed Fix - Two Changes Needed
I've confirmed this bug. Looking at the codebase, there are two issues:
1. Type definition fix (generated file - needs API spec update)
File:
src/openai/types/responses/response_output_text.py:125Change from:
To:
This allows the API to return null text values (which can happen in partial responses, tool-call-only turns, or provider edge cases).
2. Structured parsing fix (handwritten code)
The
output_textproperty insrc/openai/types/responses/response.py:555-569already has null-checking code at line 566:with a pyright ignore comment
# pyright: ignore[reportUnnecessaryComparison]- this suggests the developers anticipated null values but didn't update the type.However, the structured parsing in
responses.parse()also needs to skip null text content blocks. Looking at the lib parsing code insrc/openai/lib/_parsing/_responses.py, the parsing loop should be updated similarly to filter out output_text items with null text before attempting JSON parsing.3. Also check param file
There is likely also a
response_output_text_param.pythat may need the same fix if text can be null in requests as well (but typically requests don't have null text).Related files to update in handwritten code:
src/openai/lib/_parsing/_responses.py- skip null output_text items during structured parsesrc/openai/types/beta/agent_session_message.py:48-50- its output_text property joins content.text without null checking:The fix is straightforward and follows the pattern already started with the pyright ignore comment - just need to update the type definition to match reality.
dajiaohuang commentedon Sep 29, 2026
The focused fix is in my fork's draft PR #1: dajiaohuang#1. It accepts nullable ResponseOutputText.text, skips structured parsing for null text blocks, preserves valid neighboring text, and adds model plus sync/async responses.parse regression coverage. Upstream currently restricts PR creation to collaborators; a maintainer can review/cherry-pick this draft or add collaborator access if direct upstream submission is desired.