Codex Keeps Reconnecting? Fix Stream Disconnected Safely

stream disconnected before completion is a symptom, not one root cause. Preserve the work Codex already changed, copy the complete error and request ID, then classify the failing endpoint before changing anything. A chatgpt.com stream failure points toward service or network transport; a 127.0.0.1 failure points toward a local Codex helper; an error that appears only during remote compaction points toward a long-session path.

Do not begin by deleting .codex, clearing chat history, reinstalling repeatedly, changing DNS, or moving a live repository. Those actions can destroy useful evidence without fixing a remote incident, a blocked WebSocket, a local helper that never started, or an unavailable cloud-backed workspace.

What Success Looks Like

You should finish with:

• the repository's current changes preserved and reviewed;

• one exact failure class identified from the error URL and timing;

• a small control task that completes outside the failing thread or workspace;

• only the narrow network, local-helper, workspace, or session remedy applied;

• one sanitized evidence bundle if the failure persists.

This guide applies to Codex Desktop, the Codex IDE extension, and Codex CLI. It does not claim one permanent fix for every stream disconnect.

Prerequisites

Before troubleshooting:

• stop issuing new prompts in the failing thread;

• record the timestamp, Codex surface and version, operating system, exact URL, request ID, and reconnect count;

• save important unsaved editor buffers;

• keep credentials, private prompts, complete transcripts, and private repository paths out of public reports;

• confirm that you can inspect the repository with Git or another trusted version-control tool.

Step 1: Preserve Partial Work

Run read-only Git checks from the repository root:

git status --short
git diff --stat
git diff --name-only

Expected result: you have an inventory of modified, added, deleted, and untracked files. A disconnected response can leave useful changes, incomplete changes, or both. Review them before retrying the same instruction.

If the interrupted task ran tests or commands, do not assume their success message survived. Re-run the smallest relevant check after reviewing the diff. Aident's guide to verifying an AI coding agent's work explains why code changes and test evidence must be checked separately.

Step 2: Classify the Exact Error

Use the URL and the point of failure as the first decision boundary.

Expected result: the error belongs to one row. If the message omits a URL, use its timing: before any response, during streaming, during tool execution, or during compaction.

Step 3: Rule Out a Service Incident

Check the OpenAI status page before changing local state. OpenAI has previously documented a resolved incident named Codex stream is disconnecting intermittently, so a stream failure can be service-side.

Then open a new empty Codex task and send a bounded prompt:

Reply with STREAM_OK. Do not call tools or edit files

Expected result: STREAM_OK returns once without a reconnect loop. If the same remote endpoint fails across new tasks, projects, and devices while an incident is active, wait for recovery. Reinstalling or deleting local state cannot repair a remote incident.

If only the original long thread fails, continue to Step 6. If every task fails and the status page is clear, continue to the network checks.

Step 4: Test the Network Boundary

OpenAI's network guidance says Codex uses secure WebSocket traffic to wss://chatgpt.com/ over TCP port 443. A proxy, firewall, TLS-inspection product, secure web gateway, VPN, or idle-timeout policy can allow ordinary HTTPS while still disrupting a long-lived WebSocket.

On Windows PowerShell, confirm basic reachability:

Test-NetConnection chatgpt.com -Port 443

On macOS or Linux:

curl -I https://chatgpt.com/

These checks confirm DNS, TCP, and ordinary HTTPS reachability. They do not prove that a WebSocket upgrade or a long-lived stream is permitted.

Next, compare one small Codex task on a trusted alternate network, such as a mobile hotspot, with VPN and proxy software disabled if your policy allows it. Change one variable at a time.

Expected result: if the task succeeds on the alternate network but repeatedly fails on the managed network, ask the network administrator to verify:

• WebSocket upgrades to chatgpt.com over TCP 443;

• TLS inspection or SSL decryption that rewrites or closes the connection;

• idle timeouts for long-lived WebSockets;

• maximum frame or message-size limits;

• proxy and secure-gateway logs for the recorded timestamp and request ID.

Do not publish packet captures or HAR files without checking them for tokens, cookies, URLs, and private request content.

Step 5: Separate a Local Helper Failure

If the error names 127.0.0.1:10100, test that exact local port on Windows:

Test-NetConnection 127.0.0.1 -Port 10100
Get-NetTCPConnection -LocalPort 10100 -State Listen -ErrorAction SilentlyContinue

Expected result: a healthy local helper should own the port while the relevant Codex surface is running. If nothing is listening, fully close the app, confirm no Codex process remains, restart it once, and repeat the port check. Record the app version and whether a new empty task still fails.

Do not apply remote WebSocket fixes to a refused localhost connection. If the helper still never listens, report that exact local error and version through the matching Codex issue or OpenAI Support.

Step 6: Isolate Long Threads and Compaction

If short tasks work but a long thread fails during remote compaction, preserve a compact handoff outside the chat:

Goal:
Completed:
Files changed:
Last verified command:
Open question:
Next safe step:

Start a new task in the same repository and ask it to read the handoff plus the current Git diff before doing anything. The new task should restate the next step and run one read-only check first.

Expected result: the new task can continue from repository evidence without reconstructing the entire failed conversation. If compaction keeps repeating, follow the dedicated Codex context compaction loop guide. Do not enable undocumented feature flags copied from a forum unless the current Codex client exposes and documents them.

Step 7: Test a Cloud-Backed Workspace Safely

Recent Windows reports correlate repeated stream failures with OneDrive-backed or redirected workspaces, but that evidence does not prove OneDrive causes every disconnect. First inspect the current path:

Resolve-Path .
Get-Item . | Select-Object FullName,Attributes
git status --short

If the path is under OneDrive, confirm the files are available locally and the sync client is healthy. Do not move the only copy of a live repository while OneDrive is degraded.

Create a tiny control folder outside OneDrive:

New-Item -ItemType Directory -Path C:\CodexTest\stream-check -Force
Set-Location C:\CodexTest\stream-check
git init
Set-Content -Path README.md -Value "Codex stream isolation test"
git status --short

Open only that folder in a new Codex task and ask:

Read README.md and reply STREAM_OK. Do not edit files

Expected result: if the local control succeeds while the hydrated OneDrive workspace repeatedly fails, preserve the original, make a verified backup, and work from a deliberate local clone or copy until the provider is healthy. If both fail, return to the service and network branches.

Step 8: Update Once, Then Collect Bounded Evidence

Record the running client before updating:

codex --version

If it is behind the current supported release, update it through the same installer or package manager that owns the running binary. Restart Codex and repeat one new-task control. Avoid layering several installations on PATH or reinstalling repeatedly without a comparison result.

For a persistent failure, report:

• sanitized exact error and endpoint;

• timestamp, time zone, request ID, and reconnect count;

• Codex surface and version;

• operating system;

• whether a new empty task works;

• whether an alternate network changes the result;

• whether the workspace is local, OneDrive-backed, WSL, remote, or network-mounted;

• whether the failure begins before output, during streaming, during a tool call, or during compaction.

This is enough to distinguish major boundaries without uploading private logs or a full transcript.

Common Failure Modes

Why This Order Works

The error URL identifies which transport boundary failed. A clean status and control-task check separates a broad incident from one thread. A one-variable network comparison tests the WebSocket path. A localhost port check isolates the local helper. A tiny non-OneDrive workspace tests storage provenance without risking the main repository. Git evidence and a written handoff make the work recoverable even when the chat is not.

This follows the repeatable structure behind Aident's Ollama networking guide: use exact terminology, run reproducible checks, state expected results, cover look-alike failures, and explain why the boundary matters. For future agent work, add the repository guardrails from How to Prevent Codex from Deleting Files.

Verify One Read-Only Action With Aident Loadout

After Codex completes the STREAM_OK control, verify one external Action without pasting provider credentials into the new task. Install or update Aident Loadout with this prompt:

Follow https://aident.ai/SETUP.md

Then run:

aident account auth status
aident vault vault --action status
aident capabilities search \
  --queries '["find one connected read-only GitHub Action that searches issues"]' \
  --types '["action"]'

Inspect the selected contract before execution:

aident capabilities get --name "<canonical-action-name>"

Success means one live Action schema was inspected, zero provider secrets entered the chat, and zero repository files changed. This does not fix Codex transport; it proves that the recovered agent can discover a bounded external capability.

Use Aident Loadout to verify one read-only Action after recovery.

Sources

• Network recommendations for ChatGPT errors on web and apps, OpenAI Help Center, accessed July 29, 2026

• OpenAI service status, accessed July 29, 2026

• Codex stream is disconnecting intermittently, OpenAI status incident, resolved April 28, 2026

• Codex CLI getting started, OpenAI Help Center, accessed July 29, 2026

• Work/Codex stream disconnects with a OneDrive-backed workspace, OpenAI Codex issue, opened July 26, 2026

• Codex VS Code extension frequently disconnects, OpenAI Codex issue, opened July 27, 2026

• Codex Desktop app-server disconnect under concurrent tasks, OpenAI Codex issue, opened July 28, 2026

• The stream disconnected error is blocking my workflow, r/codex, posted July 27, 2026

• Codex reconnecting and stream errors, YouTube, published July 14, 2026

Refresh this guide when OpenAI documents a fixed client version, changes Codex WebSocket destinations, publishes a supported diagnostic command, or closes the July 2026 reports with a confirmed cause.