Codex "stream disconnected before completion": causes and fixes
What follows the colon in Codex's stream disconnected error, how many times it retries, why the ChatGPT login can't change that, and what codex exec does.
“stream disconnected before completion” means the reply Codex was receiving from OpenAI ended before the server sent its completion event. The words after the colon say why: no data for five minutes (“idle timeout waiting for SSE” or “…for websocket”), the connection closed (“websocket closed by server before response.completed”), a network failure (“error decoding response body”, “error sending request for url”), the content filter (“reason: content_filter”), or an error message from OpenAI’s server. Codex has already retried before it shows you this: five times by default, then over HTTPS instead of WebSocket. Network causes are fixed on your side (VPN, proxy, a stale base URL); the content filter by rewording; server errors by waiting. A codex exec job that runs out of retries exits with status 1.
What follows the colon
Every variant comes from one line in Codex’s error definitions, stream disconnected before completion: {0}, with the reason filled in by whichever part of Codex saw the stream end (as of release 0.170.0, November 2026). The reasons you will meet, and what each one tells you:
- “idle timeout waiting for SSE” / “idle timeout waiting for websocket”. Nothing arrived on the stream for 300,000 ms, five minutes, the default idle timeout. Either the connection died silently, or the model was still thinking: one report (#39771) shows a high-effort turn that went about 8.5 minutes without a frame and then continued. Another (#43140, on 0.153.4) shows that over HTTPS an idle timeout can hide a server error the stream had already sent.
- “websocket closed by server before response.completed” / “stream closed before response.completed”. The other end closed the connection mid-reply. It might be OpenAI’s server or anything in between that ends connections.
- A network error, such as “error decoding response body” or “error sending request for url (https://chatgpt.com/backend-api/codex/responses)”. The HTTP library failed to send the request or to read the reply. The prefix has changed between versions: reports show “Transport error: network error: error decoding response body” on 0.75 to 0.77 and “Transport error: Error while reading the server response: error decoding response body” later. The URL shows which endpoint failed:
chatgpt.com/backend-api/codexif you signed in with ChatGPT,api.openai.com/v1if you use an API key. - “Incomplete response returned, reason: content_filter”. OpenAI’s content filter stopped the reply. This one is about what is in the conversation, not the network.
- A sentence from OpenAI, such as “An error occurred while processing your request…” with a request ID. The server ended the reply with a failure code Codex has no specific handling for, and Codex prints the server’s own message. Errors it does recognise (a quota, a usage limit, a model at capacity, rate limits) get their own messages instead.
- “Responses websocket connection limit reached (60 minutes).” A WebSocket connection is only allowed to last an hour. Codex retries this on a new connection, so you should only see it in a retry line.
How many times Codex retries, and how long that takes
All of these reasons, the content filter included, are classed in the source as errors to retry with backoff. A turn gets stream_max_retries attempts, 5 by default, which is the “Reconnecting... 2/5” counter you see. On a WebSocket connection the first retry is silent, so the visible count starts at 2. When the five are used up on WebSocket, Codex prints “Falling back from WebSockets to HTTPS transport.” with the error, resets the counter and tries again over HTTPS. You only see “stream disconnected before completion” as a final error after that. Separately, request_max_retries (4 by default) covers retries of the HTTP request itself before any stream begins.
A connection that dies silently takes up to five minutes to detect each time, so a stalled turn can sit for a long while before it fails. The reporter in #38638 estimated about 25 minutes. The config reference lists all three settings, but per provider, and only for a provider you define yourself:
[model_providers.azure]
# ...the provider's name, base_url and key, as in OpenAI's example
request_max_retries = 4
stream_max_retries = 10
stream_idle_timeout_ms = 300000CopiedWith the built-in OpenAI provider, which is what a ChatGPT sign-in or a plain API key uses, you cannot change them. OpenAI’s advanced config page says “don’t create [model_providers.openai], because you can’t override built-in provider IDs”, and a user who tried reports it rejected (#38638). Nor do the docs give a way to take the built-in provider off WebSocket. The retry counts and the five-minute timeout are fixed there.
When the network is the cause
The network messages and the closed-connection messages mean something between Codex and OpenAI ended the conversation. When OpenAI’s maintainers ask about these reports, their first question is whether the reporter uses a VPN or a network proxy (#8302, #13041). That is not a finding that VPNs cause it: several reporters had neither, and none of the threads names a proxy that cuts long streams. It is still the first thing to rule out. On a server, these are the places to look:
- A VPN, a proxy, or a Tailscale exit node. A server using an exit node sends all of its internet traffic through the device at home, Codex’s connection to OpenAI included, so a weak link at home becomes part of every request. To test this, run the same prompt with the exit node or VPN off. If the errors stop, you have found the cause.
- A required proxy that Codex does not see. Codex loads environment variables from
~/.codex/.envat start (names beginning withCODEX_are skipped), so a setting there also applies to a job started by cron or a service manager, which does not read your shell profile. One user in #18960 says their retry loop stopped once they puthttps_proxyand its siblings there. - A leftover base URL or key. “No connection could be made because the target machine actively refused it” turned out, in #18960, to be an
openai_base_urlinconfig.tomlpointing at a local tool that was no longer running. In #3835 it was an oldOPENAI_API_KEYleft in the environment from another tool. Check both before anything else on a machine where other agents have been installed. - The machine’s own link. On laptops the message follows sleep and lost Wi-Fi (#3355). Two reporters in #38638 fixed it at the network layer, one by replacing a USB ethernet adapter and one by fixing the IPv6 default route.
Signed in with ChatGPT, Codex talks to chatgpt.com. With an API key it talks to api.openai.com. That changes which hosts a firewall or proxy on the path has to allow. If the cause turns out to be the sign-in rather than the network, the message changes to a 401, which the 401 guide covers.
When it is the content filter
Codex retries a content-filter stop like any other, after adding guidance about it to the conversation. A false positive on harmless code or prose tends to come back on every retry, as the reports in #43969 and #45970 describe. Each retry costs time and usage. Change what triggers it: reword the request, or start a fresh session without the material that set it off. Retrying the same thread rarely helps.
When it is OpenAI
A message from the server with a request ID, or many users reporting the same thing at the same hour, points at OpenAI’s side. In one long thread (#8302, the 0.75 to 0.77 “error decoding response body” wave) a maintainer said the cause was that larger models “take longer to generate the next batch of tokens during streaming”, longer than an HTTP timeout allowed, and that OpenAI had “mitigated” it. Nothing on your machine fixes a server-side wave: wait, then retry. If it keeps happening, the maintainers ask for /feedback from inside the session and the thread ID it gives you, posted on a new GitHub issue. A different model can help when one model is overloaded, though that message is “Selected model is at capacity” and not this one.
In a codex exec job
In codex exec, each retry prints as an error line (“Reconnecting... 2/5” and so on) without failing the run, because the error is marked as one Codex will retry. Only the error after the last retry counts, and then the run exits with status 1, as its source shows. A job that got partway is better resumed than rerun, because rerunning repeats its edits from the start. Run this from the same directory:
codex exec resume --last "continue"CopiedWhen a job fails this way, have the wrapper keep the line that says why. The words after the colon decide what to do next: rerun it later for a network or server cause, or change the prompt for content_filter.
#!/bin/sh
# Run a codex exec job; on a dropped stream, report the reason.
out=$(codex exec "$1" 2>&1)
status=$?
if [ $status -ne 0 ] && printf '%s' "$out" | grep -q 'stream disconnected'; then
printf '%s\n' "$out" | grep 'stream disconnected' | tail -n 1 \
| mail -s "codex: stream disconnected" you@example.com
fi
exit $statusCopiedReplace the address and the mail command with whatever reaches you. The rest of setting Codex up on a VPS, from sign-in to the sandbox, is in Codex CLI on a Linux server.