Codex CLI Common Errors & Troubleshooting

General triage — three questions

Before diving into specific errors, run through this 30-second check to narrow down the category:

1. Read the error type. 401/403 = authentication; 429 = rate limit; os error/port conflicts = local environment; Reconnecting/stream disconnected = network.
2. Test connectivity. Run curl -I https://api.openai.com/v1/models. A 401 response means the network is fine — the problem is auth. A timeout or connection refusal means a proxy/network issue (see the Reconnecting checklist).
3. Collect diagnostics. Inside a Codex session, run /feedback to capture request IDs, error logs, and a connection snapshot — useful if you need to file a bug report.

Error lookup table

Authentication errors (401 / login failures / headless)

401 Unauthorized — token expired

401 Unauthorized means the server received your request but rejected your credentials — your login token has expired or your API key is invalid. Steps to fix:

1. Log out and back in (ChatGPT account):
   Terminalcopy

   $ codex logout
   $ codex login

2. If using an API key, verify the key is active and your account has CLI access enabled.
3. Check for a stale OPENAI_API_KEY in your environment: env | grep OPENAI and unset it if needed.

Headless / remote server login failures

On machines without a browser (SSH servers, CI, Docker containers), Codex automatically switches to Device Code authentication. If the workspace admin has disabled Device Code auth, login will fail even for an authorized user — there is no error message that makes this obvious.

While waiting for the admin to act, two workarounds are available:

1. Copy auth.json. Complete the OAuth flow on a machine that has a browser, then copy ~/.codex/auth.json to the same path on the headless server.
2. Use an API key. Run codex login --with-api-key — this bypasses the browser flow entirely.

Login stuck on the "Sign in with ChatGPT" screen

The OAuth flow requires the browser to call back to localhost after sign-in. If that callback is blocked by a firewall or corporate network policy, the browser page stays frozen.

• Verify that the localhost callback port is not blocked by a firewall rule.
• In restricted environments, codex login --with-api-key is the more reliable option.

Rate limiting — 429

When your request volume exceeds the limit for your current subscription plan, the CLI returns 429 Too Many Requests. The CLI will display the exact time your quota resets:

Port conflict — Address in use (os error 98 / port 1455)

During login, Codex binds to port 1455 on localhost to receive the OAuth callback. If another process already holds that port — most commonly an SSH port-forwarding tunnel — login fails with Address in use (os error 98).

1. Identify and stop the process using port 1455:
   macOS / Linuxcopy

   # Find which process holds port 1455
   $ lsof -i :1455
   # Or with ss (Linux)
   $ ss -tlnp | grep 1455

2. If it is an SSH tunnel, close that connection or change the tunnel's forwarded port number.
3. Once the port is free, run codex login again.

Config and sandbox issues

Invalid model setting

If the model field in ~/.codex/config.toml references a model name that does not exist, Codex will refuse to start. The simplest fix is to remove that line and let the CLI fall back to its built-in default:

# Delete or comment out the line below
# model = "some-nonexistent-model"

Broken config file

If config.toml has a TOML syntax error (often from manual edits), Codex cannot parse it and refuses to start. The quickest recovery is to rename the file as a backup and let Codex regenerate a fresh one:

$ mv ~/.codex/config.toml ~/.codex/config.toml.bak
$ codex

Sandbox blocking commands

Codex's sandbox mode and approval settings control which shell commands the agent is allowed to run. If a command is unexpectedly blocked, review your sandbox and approvals configuration in config.toml or your launch flags — see the Commands guide for details.

WSL migration conflict

When running Codex on both Windows and WSL, if both environments point to the same CODEX_HOME (typically ~/.codex), the internal database migration history becomes inconsistent and you'll see the error migration N was previously applied but has been modified. Fix it by giving the WSL instance its own home directory:

export CODEX_HOME="$HOME/.codex-wsl"

Logs and the /feedback command

Codex writes diagnostic logs locally (as of 2026). For hard-to-reproduce issues, the fastest path is the built-in feedback command, run from inside an active Codex session:

› /feedback

/feedback automatically bundles:

• The current session's request IDs (for OpenAI-side tracing)
• Recent error log excerpts
• A snapshot of the connection state

Frequently asked questions