Codex stream disconnected before completion: Diagnose the Cause
Trace Codex stream disconnects using the full error, response events, session history and network path without blindly retrying unfinished tool actions.
Ofox 
stream disconnected before completion tells you that a Codex response did not finish as expected. It does not identify one universal cause. Read the rest of the error, check whether the transport was SSE or WebSocket, and distinguish an explicit quota or context error from a connection that closed before the completion event arrived.
Before retrying, inspect any files the agent changed and any actions its tools performed. A disconnected response does not mean that earlier commands were rolled back. This guide is for Codex users and developers operating compatible Responses endpoints. It is based on official documentation and source inspection on September 14, 2026. We have not reproduced your specific incident.
Classify the suffix, not just the headline
The current Codex SSE parser distinguishes an unfinished stream from more specific recorded errors. Its generic closed-before-completed fallback is not evidence that the user’s internet connection was necessarily responsible.
| Observation | What it establishes | First investigation |
|---|---|---|
Closed before response.completed | Normal completion was not observed | Transport, server and intermediary logs |
response.failed with a code | Provider reported a specific failure | The actual code and error message |
response.incomplete | An explicit incomplete event arrived | incomplete_details.reason |
| SSE idle timeout | No SSE event arrived within the configured idle window | Upstream delays and intermediary timeouts |
| WebSocket closed by server | A WebSocket close was observed | Route support and close details |
A readable partial answer is not proof that the response completed. In the streaming documentation, text events and response lifecycle events serve different purposes. response.output_text.done ends a text portion; it should not be treated as a substitute for the overall response completion signal.
Preserve work before repeating the task
Review the current diff, terminal output and any external action that was started. A tool can finish while the final model response fails to reach the interface. For actions with side effects, check the destination or execution record before asking the agent to repeat them.
Do not assume that an automatic retry gives exactly-once execution or that a failed-looking request is free. Those guarantees depend on the operation and provider. When continuing a coding task, describe what has already been verified and what remains uncertain so that the next attempt does not blindly rerun every step.
For a controlled diagnostic, use a new session and a short read-only task. Keep the model and route unchanged at first. If that succeeds while the original session fails, history length, compaction or a tool sequence becomes worth inspecting. It does not by itself prove a particular client bug.
Handle explicit errors on their own terms
The official API error guide separates authentication, access, rate limits and server failures. Check the response body rather than treating every failed stream as a retryable network issue.
A missing model or wrong route belongs in the model-not-found guide. A subscription allowance is different from API billing balance and from a rate limit measured over time. For account-window questions, see the Codex limit guide. Do not solve a named quota error by repeatedly increasing a network timeout.
Likewise, context_length_exceeded points to a different constraint from an idle connection. Reduce or manage the relevant context using supported client features and preserve important task state. A new empty conversation may diagnose the difference, but it is not a substitute for understanding which history the original request contained.
Inspect the actual network path
Record the endpoint hostname, proxy configuration, client version and transport. SSE and WebSocket are separate paths; a proxy that handles ordinary HTTPS requests may still have different connection lifetime or WebSocket behavior. Compare logs from the client, gateway and upstream when you control them.
Use an organization-approved standard network path as a comparison if one is available. Do not disable TLS verification or security controls to make a test pass. A certificate error deserves certificate-chain diagnosis, not an insecure bypass.
Check whether failures happen after a consistent period without events, only on a particular route, or only during tool-heavy turns. Those patterns suggest what to test next. They are not sufficient evidence to blame the model provider, the proxy or the client without additional observations.
Understand idle timeout and retry settings
The current Codex configuration reference distinguishes custom-provider stream_idle_timeout_ms, stream_max_retries and request_max_retries. The documented defaults are 300,000 milliseconds, five stream retries and four request retries respectively. These defaults describe the documented settings as of the review date. The stream settings are documented for SSE; do not assume they control every WebSocket failure.
An idle timeout measures inactivity in the relevant stream, not the maximum duration of the entire task. Raising it cannot prevent a server or intermediary from closing a connection for another reason. Change it only when the evidence points to that timeout and your upstream supports the longer wait.
Use the existing config.toml guide to locate the effective configuration. A setting in an unused profile will not change the running session. Avoid copying an unverified switch that claims to disable WebSocket support across every Codex version.
Build a useful incident record
Keep the start and failure times, operating system, client version, transport, endpoint hostname, full error suffix and request or response ID. Add whether a fresh session succeeds, whether tools had already executed, and the shortest harmless task that reproduces the issue.
Remove secrets, cookies, authentication files and private repository contents before sharing logs. Historical issues can provide comparison cases, but check their dates and status. For example, Codex issue 4302 is a closed historical report; it is not evidence that the same old defect remains unfixed today.
Frequently asked questions
Does this error always mean my network failed?
No. The prefix covers an unfinished response path. The full suffix, lifecycle event and provider error are needed to separate connection failures from explicit request failures.
Can I safely ask Codex to repeat everything?
Check what already happened first. File changes and external tool actions may have completed before the stream failed, and repeating them can duplicate work or side effects.
Should I keep increasing the timeout?
Only if the relevant idle timeout is the observed cause. A larger client timeout does not repair invalid credentials, unavailable models, exhausted allowances or upstream connection policies.
Frequently Asked Questions
- What does stream disconnected before completion mean?
- A Codex response failed to finish as expected. The full error distinguishes an explicit failure from a connection that closed early.
- Is response.output_text.done enough to confirm completion?
- No. It ends a text portion, not necessarily the complete response lifecycle.
- Does a failed stream undo executed tools?
- No rollback should be assumed. Inspect the operation state before retrying.
