GuidesRunning & maintaining

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.

November 18, 2026The Everpod team
The short answer

“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:

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 = 300000
Copied

With 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:

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"
Copied

When 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 $status
Copied

Replace 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.

Run Codex on an always-on developer pod.

A developer pod is a permanent cloud computer (VPS), set up and secured for you, with your pick of Claude Code, Codex, OpenCode, Pi, Hermes and OpenClaw installed. Run more agents at once than your laptop can hold, and keep them working when it’s closed. From $24 a month, built in about ten minutes.