Responses stream parser crashes when terminal response.output is null

[yelixir-dev]

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

When a Responses stream emits useful deltas or output-item events but the terminal response.completed payload contains response.output: null, the Python SDK parser raises:

TypeError: 'NoneType' object is not iterable

The crash path is in src/openai/lib/_parsing/_responses.py, where parse_response() iterates response.output directly:

for output in response.output:

If the terminal response has output = None, this fails before callers can inspect the already-streamed events or recover from the malformed terminal payload.

A downstream Hermes Agent report and workaround are here:

NousResearch/hermes-agent#32883

Hermes has now added defensive recovery around this shape, but the underlying SDK parser still appears to need a null guard so stream.get_final_response() / response parsing does not turn a malformed terminal output field into an uncaught client-side TypeError.

To Reproduce

A minimal fake stream shape is enough:

1. Stream emits reasoning/text/output-item deltas.
2. Stream ends with response.completed whose response.output is null.
3. stream.get_final_response() parses the terminal response.
4. parse_response() attempts for output in response.output and raises TypeError: 'NoneType' object is not iterable.

Expected behavior

parse_response() should tolerate a null/missing output list and produce an empty parsed output list, or otherwise raise a typed SDK/API error with context instead of an incidental TypeError.

The smallest defensive patch appears to be:

-    for output in response.output:
+    for output in response.output or []:

A regression test should cover a Response / parsed response object whose output is None.

Additional context

The downstream Hermes workaround validates this failure class by:

• catching the SDK TypeError("'NoneType' object is not iterable") from the stream parser,
• falling back to responses.create(stream=True),
• backfilling missing response output from already-streamed output items, text deltas, or reasoning deltas,
• guarding response.output_text access because convenience accessors can also fail on partial/malformed output.

Hermes validation from the linked issue:

112 passed, 1 warning

Library version

Observed against OpenAI Python SDK 2.24.0 in the downstream Hermes environment. Current main still appears to iterate response.output without a null guard in src/openai/lib/_parsing/_responses.py.

[Xsidz]

Working on this in PR #3629 (same root cause).

[marcuswood-oai]

Thanks for the report! Fixed on main by #3345, which handles null response output and preserves finalized streamed items when the completion has null or missing output.