Codex Desktop “Reconnecting” is too ambiguous: network timeout vs auth/session failure

Codex
1

Hi everyone,

I ran into a persistent “Reconnecting” loop in Codex Desktop on macOS. I eventually fixed it, but the hard part was not the fix itself. The hard part was understanding what “Reconnecting” actually meant.

In my case, the same UI state seemed to cover at least two different failure modes.

Environment

  • macOS
  • Codex Desktop
  • ChatGPT account sign-in
  • Network environment sometimes requires an explicit local proxy

What happened

Codex Desktop kept showing “Reconnecting” and did not recover after waiting or reopening the app.

At first, the UI did not make it clear whether this was:

  • a network reachability problem
  • a WebSocket timeout
  • an expired or invalid session
  • an MFA/authentication issue
  • a temporary service-side issue

What I found

1. Network timeout

In one case, the logs suggested a WebSocket timeout. My environment uses a local proxy, and Codex Desktop did not appear to use the same network path as my browser.

Adding proxy variables to ~/.codex/.env helped in that environment.

I realize this is environment-specific and may not apply to most users. I am mentioning it mainly because the UI only showed “Reconnecting”, not “network timeout” or “cannot reach server”.

2. Auth/session issue

In another case, the connection appeared to reach the service but still returned to “Reconnecting”.

After enabling multi-factor authentication on my ChatGPT account, fully quitting Codex Desktop with Cmd + Q, and reopening it, the issue stopped.

I cannot say for sure whether MFA itself was the root cause, or whether the full sign-in/session refresh solved it. But from the user side, it looked like an auth/session state problem hidden behind the same “Reconnecting” message.

Feedback

It would be very helpful if Codex Desktop exposed more specific reconnect reasons, for example:

  • Network timeout
  • WebSocket handshake failed
  • Authentication/session expired
  • MFA required
  • Service unavailable
  • Rate limit or quota issue

Even a small “View details” link near the Reconnecting message would make this much easier to diagnose.

Question

Is there a recommended way to distinguish these causes from Codex Desktop logs today?

If anyone has a better diagnostic flow for this, I would love to learn it.