Codex not working? 5 checks that fix it

Don't reinstall yet. Almost every "Codex is broken" moment is one of three things: auth, rate limits, or a bad config value. This checklist isolates the cause in minutes.

Step 1: Confirm you are authenticated

Expired or missing credentials are the most common culprit. Run codex in your terminal:

• If authenticated: Codex starts normally, ready for prompts
• If not authenticated: Opens browser for OpenAI login

Auth troubleshooting

• Token expired: Re-authenticate by running codex and completing the browser flow
• Password changed: Old tokens are invalidated; re-authenticate
• Session revoked: Re-authenticate after revoking old sessions

Step 2: Rule out rate limits

If Codex worked earlier but now stalls or fails, you likely hit a rate limit. The CLI returns a 429 with a reset time.

Rate limit solutions

• Wait: The error includes a reset time; quota recovers on its own
• Switch accounts: With more than one OpenAI account, use CodexUse to jump to a profile that still has headroom
• Check usage first: CodexUse shows estimated usage per profile, so you switch to the right one
• Move the work off OpenAI: a custom-provider profile runs a non-OpenAI model in the Codex App on your own provider credential, so it uses no OpenAI quota

Step 3: Verify network and OpenAI status

Sometimes the problem is not on your end:

• VPN interference: Some VPNs block or throttle OpenAI traffic; try disconnecting
• Corporate proxy: Enterprise networks may require proxy configuration
• DNS problems: Try switching DNS temporarily
• OpenAI outage: Check status.openai.com for service issues

Step 4: Inspect your config

A bad value in the Codex CLI config can break things quietly. The usual offenders:

• Invalid model: Remove the model setting to fall back to the default
• Sandbox blocking: If commands fail for no clear reason, check your sandbox mode
• Reset config: Rename config.toml and restart Codex on defaults

Step 5: Confirm your CLI version

Make sure you are running the version you think you are:

Version issues

• Multiple installations: You might have npm and brew versions conflicting
• Old version: Update to latest; some issues are fixed in newer releases

Troubleshooting table

Symptom	Likely cause	Action
"Command not found: codex"	CLI not installed or not in PATH	Run npm install -g @openai/codex
Browser opens every time you run codex	Auth token keeps expiring or not saving	Check file permissions; ensure config directory is writable
Hangs without any output	Network timeout or slow connection	Check internet; disable VPN if using one
"Model not found" error	Invalid model name in config	Remove model line from config or use a valid model
Works in terminal, fails in scripts	Different shell environment	Use absolute path to codex binary
CodexUse shows expired profile	Refresh token invalidated by OpenAI	Delete the profile and re-add with fresh authentication

When reinstalling is actually warranted

Reinstall the Codex CLI only when:

• You have tried all the above steps
• The CLI itself crashes or shows internal errors (not auth/network issues)
• You are updating from a very old version with known breaking changes

What to avoid

• Reinstalling as the first troubleshooting step. It rarely helps
• Deleting your Codex config directory without backing up first
• Assuming "it is broken" without checking auth and rate limits
• Running as sudo/root. The CLI does not need elevated privileges

Related