Introduction
If you regularly work with Codex and similar command-line AI coding assistants, you have likely encountered a common failure state. Midway through code generation, the dialogue session freezes. The status bar starts showing Reconnecting 5/5, counting sequentially from 1/5, 2/5, all the way to 5/5. Once the counter hits the final iteration, the entire conversation terminates, and all accumulated context is lost.
Many users first assume this error originates from the model backend. They rotate API keys, switch model variants, and restart their local machine, yet the issue persists. In most real-world troubleshooting cases, the root cause lies not with the model service itself, but in network link characteristics and intermediate routing devices. This article breaks down the full diagnostic workflow for the Reconnecting 5/5 error and introduces a single configuration parameter that resolves the problem in most environments.
1. What Does “Reconnecting 5/5” Actually Mean?
1.1 The Issue Is Not A Down Server, But A Broken Long-Lived Stream
Codex is an interactive command-line tool. Unlike standard discrete HTTP request-and-response workflows, it maintains a persistent long-lived connection to stream incremental content generated by the large language model. This connection behaves like an active phone call: the channel remains occupied even during periods where the user is reading, thinking, or typing, with no active data transfer.
The message Reconnecting 5/5 indicates this persistent stream has been terminated. The client application automatically attempts recovery, and has reached its fifth retry attempt. The term “reconnect” differentiates this behavior from a simple retry. Retry means submitting the identical request again from scratch. Reconnect attempts to re-establish the communication channel and resume the unfinished session, preserving existing conversation context.
A critical distinction: Reconnecting messages rarely indicate the backend model service has crashed. If the service itself failed, users would typically receive explicit 5xx HTTP error codes or outright request rejection. Reconnect events usually signal that the backend server never detected the disconnection event; the breakage occurs somewhere within the intermediate network path.
1.2 Why The Retry Mechanism Is Limited To 5 Attempts
The difference between retry and reconnect requires clarification. Retry restarts a request from the beginning. Reconnect restores the tunnel and continues the prior workflow. Codex sessions often build up substantial context over time. Aborting immediately after a dropped connection creates a poor user experience, so the client retains session state and tries to resume the connection.
The five-retry limit acts as a buffer for transient network fluctuations. Early failures may be caused by brief packet jitter and resolve automatically. Later failures suggest a persistent environmental fault. Exponential backoff logic applies, with wait intervals increasing sequentially such as 1 second, 2 seconds, and 4 seconds. This creates the perception of continuous reconnection attempts rather than immediate failure.
Use this simple rule of thumb: failures on the first or second attempt may be random network noise. If the sequence reaches 5/5 repeatedly, there is a permanent breakpoint within the network path that requires investigation.
1.3 Quick Classification Table To Narrow Down Root Cause
When troubleshooting, avoid immediately modifying code or configuration. First classify the failure by when the disconnection occurs. The table below helps quickly narrow the source of the problem.
| Observed Symptom | Likely Root Cause Category |
|---|---|
| Reconnect prompt appears immediately after opening a session | Network egress, DNS, authentication or initial configuration error |
| Reconnect appears after the session has run for some time | Idle timeout, policy enforcement, NAT connection aging |
| Disconnection reliably triggers at exactly the same step | Excessively long single message, backend processing timeout |
| Problem disappears when switching to an alternate network | Intermediate network equipment with strict connection policies |
The case described in this guide falls into the second category: sessions run normally for a period, then drop randomly. This shifts troubleshooting focus from request payload content to the underlying network link.
2. End-to-End Troubleshooting Workflow: From Network Baseline To Session Keep-Alive
2.1 Step 1: Validate The Basic Health Of Your Network Path
When diagnosing network issues, start by testing the connection path from your local machine to external internet resources, before touching Codex settings. A simple curl command measures TCP connection time and time-to-first-byte (TTFB).
Focus on two key metrics: connect for TCP handshake latency, and ttfb for the delay before receiving the first byte of server response. Low values, in the tens of milliseconds, confirm your base network is functional. If even simple HTTPS requests are slow or time out, Codex reconnection failures are a symptom, not the core problem.
In the author’s test environment, output was connect=0.021 ttfb=0.172 total=0.262. This confirmed the fundamental internet connection worked correctly. The issue was not total loss of connectivity, but long-lived streams being forcibly terminated under specific conditions.
2.2 Step 2: Remove Stale Residual Network Environment Variables
Many desktop environments retain leftover network environment variables from prior debugging work. These variables override default routing rules for Codex and other command-line tools. If the variable references an obsolete local endpoint, Codex will attempt to use that invalid path before triggering reconnection logic.
Run printenv inside your terminal to list all active environment variables and scan for stale network routing entries. Clear any obsolete variables and restart Codex for testing.
This step eliminated one interfering factor in the original investigation: an old test variable pointing to a local port that no longer existed. After removing the variable, the interval between reconnection attempts increased, but the problem persisted. This confirmed the true breakpoint existed further downstream.
2.3 Step 3: Isolate The Root Cause: Idle Timeout
The most critical observation during investigation was a consistent pattern. Every Reconnecting event occurred after the user paused activity and left the session idle. The disconnection happened during silence, not while submitting new prompts.
This detail is highly diagnostic. Ordinary request failures usually stem from issues with the request itself. Connections dropped after prolonged silence almost always point to idle timeout: intermediate network hardware reclaiming inactive connections.
To validate this hypothesis, a simple test was performed. A new Codex session was opened, left idle for three full minutes, then a simple ping message was sent. The Reconnecting sequence triggered immediately. Three minutes of inactivity was enough to activate the recovery mechanism of intermediate network devices.
2.4 Step 4: Capture Connection State During Failure
If conditions permit, capture outbound traffic state at the moment of failure. The original investigation used built-in packet capture tools to observe traffic flow. After connection establishment, both endpoints remained silent for roughly 100 seconds. The remote device then sent a reset packet to terminate the tunnel.
This observation eliminated DNS issues, authentication failures, and Codex internal configuration bugs. The root cause was purely NAT idle aging. The objective became clear: prevent the connection from appearing idle.
3. The Keep-Alive Fix: One Line Of Configuration
3.1 Why Intermediate Hardware Drops Seemingly Healthy Connections
Many users are confused why a connection with no explicit error gets dropped automatically. Most home and office internet traffic passes through NAT (Network Address Translation) gateways, including consumer routers and corporate egress gateways.
These devices maintain a mapping table for every outbound connection to route return traffic back to the originating local machine. These mappings are not permanent. To conserve memory resources, each mapping entry has an idle timeout. Common values range from 30 seconds to 120 seconds. If zero data flows across the mapping for the full timeout window, the hardware marks the connection as abandoned and silently deletes the mapping.
The device sends no notification to local or remote endpoints. It simply removes the route entry. The connection appears valid until the next data transmission attempt, at which point the mapping no longer exists, and the client begins reconnecting.
Codex long-lived streaming connections are extremely vulnerable to this behavior. Unlike web pages that maintain constant background traffic, the stream can sit silent for extended periods while the user reads generated code. This idle state triggers NAT cleanup.
3.2 Single Configuration: Set Keep-Alive Interval Below NAT Timeout
The solution is straightforward: transmit tiny heartbeat packets during idle periods, to inform intermediate devices the connection remains active and should not be purged.
The configuration entry can be applied as an environment variable, one single line:
This parameter instructs Codex to send a heartbeat packet every 10 seconds. The 10-second interval was selected because most NAT idle timeouts are at minimum 30 seconds. A 10-second heartbeat ensures activity refreshes the mapping before the timeout threshold is hit. After applying this variable and restarting Codex, the Reconnecting 5/5 error no longer appeared.
Note that the environment variable name varies slightly between different Codex releases. Some versions use CODEX_KEEPALIVE_INTERVAL. Users can check built-in help documentation for the exact supported parameter name in their build, but the core principle remains: define a heartbeat interval.
3.3 Validate The Fix: Long Duration Idle Testing
After applying the configuration, subjective observation is insufficient. Run a standardized validation test. Restart Codex, open a session, leave the window idle for 30 minutes with no input, then send a new message.
In the first validation test, messages submitted after the idle period returned results without any reconnect prompt. Additional testing with a full hour of idle time also succeeded. Packet inspection confirmed small heartbeat packets transmitting approximately every 10 seconds, verifying the environment variable was loaded correctly.
Adopt this validation standard: idle the session for longer than the original disconnection interval before sending messages. If reconnection still occurs, proceed to further troubleshooting.
3.4 Fallback: Configuration File If Environment Variables Are Ignored
Environment variables are not universally supported across all Codex builds. If the tool shows no response after exporting the variable, the current client version may not read this parameter. In this case, edit the global configuration file inside the client data directory, adding this TOML entry:
Save changes and restart Codex. Both approaches achieve identical behavior: periodic heartbeat packets during idle periods. Environment variables are preferred because they apply automatically across all new sessions after shell startup configuration.
4. Extended Troubleshooting For Cases Where Keep-Alive Alone Fails
4.1 Outdated Client Builds With Reconnection Logic Defects
The keep-alive parameter resolves approximately 90% of reconnect cases, but not every scenario. Old client builds may contain bugs within the reconnection module. Heartbeats may transmit, but the backend fails to acknowledge them, or reconnection attempts omit original session identifiers. In these cases, parameter tuning only provides temporary relief, and upgrading the client build is required.
After upgrading, repeat the full idle test. Multiple users have reported identical symptoms that persisted after applying keep-alive settings, only resolved by installing a newer client release. It is recommended to prioritize version upgrades alongside configuration adjustments.
4.2 Custom API Endpoints And Gateway Keep-Alive Requirements
If you are not using default endpoints and route traffic through a custom API gateway or internal model ingress service, the problem may not sit purely on the client side. Gateways also maintain connection state and enforce idle policies. Client-side heartbeats only tell the gateway “the client remains active”, but the gateway itself may have shorter timeout windows that still terminate the stream.
This scenario is common with self-hosted model routing infrastructure. You must align the heartbeat interval with the gateway’s timeout rules. Check gateway logs for periodic disconnection events, and verify the gateway supports TCP keepalive probing.
When building custom AI application stacks, developers frequently deploy an API gateway to manage access and routing across multiple LLM endpoints.
4.3 Wireless Adapter And Router Power Saving Modes
A frequently overlooked source of failure is wireless network card power management. When idle, laptop Wi-Fi adapters can enter low-power sleep states and temporarily suspend radio transmission. Even if Codex sends heartbeat packets, the sleeping wireless hardware cannot transmit them. The packets never leave the local machine.
Check router NAT timeout values. If the timeout is set to 120 seconds, the heartbeat must reliably transmit before expiry. For corporate environments where router settings cannot be modified, disable power-saving features on the wireless adapter in your device control panel.
4.4 Corporate Network TLS Inspection And Certificate Rewrite
Corporate networks often implement TLS inspection at the network egress point. The gateway decrypts and re-encrypts all traffic, creating a new encrypted tunnel. The gateway maintains its own connection timeout independent of the end-to-end TCP stream. In this environment, client-side keep-alive settings will not work.
You must import the network gateway root certificate into your local trust store, so the client recognizes the rewritten TLS tunnel as trusted. A simple diagnostic test: confirm the connection stays stable on a home network, and only begins reconnecting after switching to the corporate network. This pattern confirms inspection policies are the root cause.
5. From Temporary Patch To Permanent Setup: Persist The Keep-Alive Setting
5.1 Automate The Variable For Every New Terminal Session
Manually exporting the environment variable only persists for the current terminal session. After closing the window and re-opening a new shell, the variable is lost. To apply the configuration automatically on startup, add the export command to your shell startup file.
New terminal windows will load the variable automatically when Codex launches. Avoid running the command repeatedly to prevent duplicate entries within the startup file. After modifying the file, run source ~/.bashrc or restart your terminal for immediate activation.
5.2 A Three-Minute Diagnostic Template For Future Reconnect Incidents
This structured workflow can be reused whenever Reconnecting errors appear:
- Run curl HTTPS test to validate base internet connectivity.
- Run printenv to inspect environment variables and remove stale network routing configurations.
- Check client version and install updates if a newer release exists.
- Apply keep-alive configuration and perform a minimum 15-minute idle test.
- If the issue persists, investigate Wi-Fi power saving, router NAT timeouts, corporate gateway and certificate policies.
This sequence separates problems into network baseline, connection parameters, or intermediate device policy. It eliminates blind trial-and-error testing.
5.3 Final Guidance: Keep-Alive Intervals Are Not Optimized At Lower Values
An important caveat: smaller keep-alive intervals are not always better. If you reduce the interval to 1 second, intermediate devices will retain the connection, but continuous tiny packets add unnecessary traffic volume, increase power consumption, and create meaningless request pressure for backend services.
A range of 10 to 15 seconds is optimal. It covers nearly all standard NAT idle timeout thresholds without excess overhead. When troubleshooting network issues, modify only one parameter at a time. Changing multiple settings simultaneously makes it impossible to identify which adjustment resolved the failure.
For most users encountering Reconnecting 5/5 in Codex, skip immediately swapping network environments. Apply the keep-alive configuration with a 10-second heartbeat and run a long idle session test. This single adjustment resolves the majority of idle stream termination issues.
International access: https://4sapi.com
Domestic access: https://4sapi.org
