Codex RescueTroubleshooting library
Codex errors & troubleshooting
Connection, login, MCP or a session that won’t move. Start with the part that broke.
How to narrow down a Codex error
Keep the exact error line, the client you used and the step that failed. Similar wording can have different causes; these routes help you choose a first check, not claim a diagnosis from a pasted message.
- Response stops or disconnects: start with connection errors and compare official service status.
- Command missing or update fails: use installation and update checks; first identify which executable and environment are active.
- Browser sign-in or callback fails: follow login-stage checks before changing local credentials.
- MCP server or tools missing: distinguish startup failures from a connected server that exposes no tools in MCP troubleshooting.
- A turn or session is stuck: preserve the task and use the session recovery guides.
If the message says an allowance is exhausted, use the usage-limit guide instead: a limit notice does not by itself identify a software fault or public outage.
Find a troubleshooting guide
-
Codex error submitting message: what to check
Save the prompt and read the full error suffix, then check whether your message is already in the conversation or queue before resending.
-
Codex not working? Check outage or setup
Compare the live Codex status report with your first failure time, then follow the branch matching your exact error.
-
Codex mcp-server removed: migration options
Read the integration's launcher first: is it hosting Codex for another client or connecting Codex to external tools?
-
codex: command not found after installing
Check which shell you are in, then open a brand-new terminal.
-
Codex config.toml errors and fixes
Search config.toml for any table header that appears twice, and on the CLI read the path:line:column it prints.
-
Codex config.toml location and overrides
Check CODEX_HOME in the affected environment before opening the default user configuration.
-
Codex login failed? Troubleshoot sign-in
Identify whether the browser, local callback or token exchange failed; use the callback port shown by your client.
-
Codex MCP startup failed: file not found
Find the client name in backticks in the warning, then look it up in your configuration.
-
Codex MCP tools not showing: checks and fixes
Run /mcp in the TUI (or open the desktop app's MCP UI) to see whether the server is listed as connected before assuming it failed to start.
-
Codex model at capacity: what to check
Check OpenAI's current status and record the exact error, time, model and client before retrying once.
-
Codex model metadata not found: what to check
Check whether a short request actually succeeds, then record the warning and exact model identifier.
-
Codex model not supported: account check
Record the exact model name and client, then check whether that model is available to your account and workspace.
-
Codex resume failed: recover your next steps
Check whether the failure began right after a Codex client update, since one reported resume failure followed an update.
-
Codex session stuck or compacting: what to do
Save your work, then check for pending approvals, tool activity and repeated compaction before starting another turn.
-
Codex stdin is not a terminal: fix
Check whether you want an interactive conversation or an automated script; they use different CLI entry points.
-
Codex: stream disconnected before completion
Check whether the client is still retrying or running tools before asking it to continue once.
-
Codex task creation timeout: fix
Save your unsent prompt, check whether a task was created anyway, then compare new-task creation with an existing conversation.
-
Codex update failed: five causes to check
Identify which install method you used (standalone installer, npm, Homebrew, or a manual archive), because that decides how you update.
-
Codex VS Code not loading: fixes
Record whether VS Code is local or remote, then inspect the Codex extension log for the first repeated error.
-
Codex Windows sandbox setup failed
Record the exact setup error and whether a Windows administrator prompt appeared; these distinguish different failure stages.
No published guides match those filters. Clear a filter to see more.