Error messages

stream disconnected before completion

stream disconnected before completion

Codex streams each reply to you as it's generated, over one long-lived connection. This error means that connection closed before OpenAI's server sent the event that marks the response as finished. The line always has a colon and a reason after it:

stream disconnected before completion: Transport error: error decoding response body

It's one of the most-reported errors Codex has. A GitHub search on September 23, 2026 turned up 602 issues quoting it, and people were still filing new ones that week. We read the retry code in openai/codex and the 0.156.1 release, and went through the long thread where OpenAI's engineers tried to pin it down.

Codex retries it before you see it

The source describes it as an error that happens "after the HTTP handshake has succeeded" and before the reply completes, and it's treated as temporary. Codex waits and resends the request, showing a counter while it does:

Reconnecting... 2/5

The limit is five by default (the config reference lists stream_max_retries with "default: 5"). On builds that talk to OpenAI over WebSockets, the first retry is hidden to cut down on noise, so a single blip usually never reaches you. When all five fail and a fallback is available, Codex prints Falling back from WebSockets to HTTPS transport. and starts the count again over plain HTTPS. Only after that does the turn end with the error on its own line.

In older versions the retries looked different. The 0.38.0 report that became the main thread showed five lines like ⚠️ stream error: stream disconnected before completion: Transport error: error decoding response body; retrying 1/5 in 181ms… before the final failure. If you see that shape, you're on an old build and updating is the first step.

What OpenAI's engineers found

The message covers several unrelated failures, and OpenAI's own people said so. An OpenAI engineer posting as pakrym-oai, working the thread in October 2025, wrote "I tend to believe there are multiple underlying causes behind the same error message", and asked everyone for the same five things. Did they have a VPN on? Did it persist once it started, or go away after /new? How full was the context? Were images part of the turn? And how long after sending did it fail?

Those questions are a decent checklist on their own. In November, Eric Traut closed the thread saying they'd "fixed many bugs" behind the error and asked anyone still seeing it on a recent version to open a new issue. Since then the reports have been spread across fresh threads instead of one.

Fixes that worked for people

A VPN or a flaky network comes up again and again in that thread. One user on 4G and 5G built Codex with TCP keepalive switched on and reported the error stopped entirely. A developer routing Codex through their own proxy found the connection was cut whenever the stream went quiet for about ten seconds. If you're on a VPN, try a turn without it before anything else.

Images are the second pattern. One linked issue is titled "using view_image tool on .avif causes repeated stream errors", so if the failures started when a screenshot or an unusual image format entered the conversation, start a fresh session without it.

If it happens on every turn of one session but a new session is fine, start fresh with /new and carry the task over. If it follows you everywhere, run /feedback right after it fails. That uploads the logs, and a request ID on the error line (the request id: suffix, or the ID inside the help-center variant) is what OpenAI asks for.

You can't raise the retry count or the idle timeout for OpenAI's own endpoint, by the way. Those settings live under a custom [model_providers.<id>] block, and the advanced config page says outright that you can't override the built-in openai provider. The five-minute idle default only becomes adjustable for a proxy or an Azure deployment you've defined yourself.

The variants people paste

The text after the colon is the underlying cause, passed through. The request-ID form turns up a lot:

stream disconnected before completion: Transport error: Error while reading the server response: error decoding response body, request id: 9a2dd9313bffe5b5-DFW

and so does one where the server itself said something went wrong, ending in "contact us through our help center at help.openai.com if the error persists". That one reads as a failure on the server while it was handling your request, and its own advice is to retry. When the retries give up on an HTTP status instead, you get exceeded retry limit, last status: followed by the code.

If Codex tells you the model “is at capacity” instead, that's a different refusal, and one Codex won't retry for you.