Codex errors & troubleshooting

Find a troubleshooting guide

Category All categories ConnectionInstallationLoginMCP & ConfigurationSessions

Client Any client Codex CLIDesktop appIDE extension

Operating system Any system LinuxmacOSWindowsWSL

Showing all 15

• Where is the Codex config file? (config.toml location and layers)

  Open ~/.codex/config.toml on macOS or Linux, or %USERPROFILE%\.codex\config.toml on Windows.

  Installation Codex CLI, Desktop app, IDE extension Windows, macOS, Linux documentary evidence

• Codex error submitting message: timeout or missing queued message

  Save the prompt and read the full error suffix, then check whether your message is already in the conversation or queue before resending.

  Sessions Desktop app macOS reported evidence

• Codex: MCP startup failed with 'No such file or directory'

  Find the client name in backticks in the warning, then look it up in your configuration.

  MCP & Configuration Codex CLI, Desktop app macOS, Linux, Windows reported evidence

• codex: command not found after installing

  Check which shell you are in, then open a brand-new terminal.

  Installation Codex CLI Any platform documentary evidence

• Codex sign-in fails: which stage actually broke

  Identify the exact line your client printed — a token-exchange error, a localhost:1455 callback failure, or no error at all — because each points to a different stage.

  Login Codex CLI, IDE extension Any platform reported evidence

• Codex MCP server added but its tools never appear

  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.

  MCP & Configuration Codex CLI, Desktop app, IDE extension Any platform reported evidence

• Codex app freezes with no error when config.toml has duplicate tables

  Search config.toml for any table header that appears twice, and on the CLI read the path:line:column it prints.

  MCP & Configuration Desktop app macOS, Windows, Linux reported evidence

• Codex resume failed: cannot reopen a session

  Check whether the failure began right after a Codex client update, since one reported resume failure followed an update.

  Sessions Codex CLI, Desktop app, IDE extension Windows, macOS reported evidence

• Codex session stuck: not producing output (context / compaction)

  Watch for a 'Compacting context' status line with an elapsed timer before deciding the turn has hung.

  Sessions Codex CLI, Desktop app, IDE extension Windows, macOS reported evidence

• Codex: stdin is not a terminal — interactive shell or script?

  Check whether you want an interactive conversation or an automated script; they use different CLI entry points.

  Installation Codex CLI Any platform reported evidence

• Codex: stream disconnected before completion

  Ask Codex to continue once. If it disconnects again, compare a short prompt in a new session before changing settings.

  Connection Codex CLI Windows reported evidence

• Codex error creating task: timeout — checks before you reset

  Save your unsent prompt, check whether a task was created anyway, then compare new-task creation with an existing conversation.

  Sessions Desktop app Windows, macOS reported evidence

• Codex: update failed, wrong version, or installed with the wrong method

  Identify which install method you used (standalone installer, npm, Homebrew, or a manual archive), because that decides how you update.

  Installation Codex CLI, Desktop app Windows, macOS documentary evidence

• Codex not loading in VS Code: find what the spinner is hiding

  Record whether VS Code is local or remote, then inspect the Codex extension log for the first repeated error.

  Installation IDE extension Windows, Linux reported evidence

• Codex Windows setup didn't finish: helper_failed and UAC checks

  Record the exact setup error and whether a Windows administrator prompt appeared; these distinguish different failure stages.

  Installation Desktop app Windows reported evidence