Common Codex errors and fixes

1. Save task progress, switch to an available model or retry later, and check OpenAI service status.
2. If only the old thread fails, start a new one with a handoff. If all models keep failing, submit the time, version and error type via /feedback.

/model

1. Check the active account, workspace, and 5-hour/weekly reset times on the usage page.
2. If quota still appears available, save progress and sign in again to the correct account. If the mismatch persists, keep a redacted screenshot and timestamp.

API keys use OpenAI Platform billing and limits, not the Codex allowance in a ChatGPT plan. Custom providers may have their own rules.

codex login status

codex logout
codex login

1. Confirm the sign-in method. ChatGPT users should re-authenticate first; dummy alone is no reason to create an API key.
2. For a custom provider or API key, inspect provider authentication; dummy may also be a local placeholder.

codex login status

codex logout
codex login

1. Check sign-in status and the target provider. Confirm whether you use ChatGPT sign-in or an API key.
2. ChatGPT users can save progress, sign out and sign in again. API key users should check key status, organization and endpoint.

API keys use OpenAI Platform billing and limits, not the Codex allowance in a ChatGPT plan. Custom providers may have their own rules.

codex login status

codex logout
codex login

1. Run Doctor; check VPN, proxy, DNS, firewall and custom CAs. Compare using a phone hotspot.
2. Compare CLI and Desktop with the same account and network. If both fail, check service status and custom providers.

codex doctor --summary

1. Run Doctor and compare another network. Confirm that the proxy or firewall allows WSS.
2. If only this network fails, inspect DNS, certificates and IPv4/IPv6 routing. Permanently disabling IPv6 is not the default fix.

codex doctor --summary

1. Inspect openai_base_url, model_provider and the provider base_url in the active user configuration.
2. Confirm the endpoint and listener are still needed. Back up config, correct stale overrides and restart. Remove keys and private URLs before sharing config.

printenv CODEX_HOME

$env:CODEX_HOME

1. Start a new thread from a saved handoff. Verify repository state before continuing unfinished steps.
2. Update docs/codex-handoff.md at milestones, limit tool output and put durable rules in AGENTS.md.

1. Look for server_overloaded, context_window_exceeded or connection errors in the same log section and follow those checks.
2. Update the client. If the old thread remains stuck, resume in a new thread from the repository and handoff instead of repeating /compact.

1. Check /permissions and the working directory. Confirm the target file is within the writable roots.
2. If chat works but dependency installation or curl fails, check command network_access. Change only permissions the task needs.

/permissions

1. Inspect the repository root, worktrees and Git status. Check whether the failing path is Git metadata.
2. After editing and testing, use permitted approval for the specific Git operation or commit in your own terminal. Deleting a lock does not fix permissions.

git rev-parse --show-toplevel
git status --short
git worktree list

1. Check IDEs, Git clients and terminals for unfinished Git operations. Wait for them to complete first.
2. Only handle the specific lock manually after confirming no Git process is active and the lock is stale. Never delete the whole .git directory.

git rev-parse --show-toplevel
git status --short
git worktree list

1. Check whether the MCP server is enabled, its tools and auth status. For OAuth servers, try mcp login again.
2. If it still fails, inspect required environment variables, processes and server logs, then the protocol. Codex account sign-in is separate from MCP sign-in.

codex mcp list

codex mcp login SERVER_NAME

1. Check /status, CODEX_HOME, CLI flags and the selected profile. Project config loads only in trusted projects.
2. Check CLI → project → profile → user → managed/system → defaults. Verify whether provider and auth settings permit project-level overrides.

printenv CODEX_HOME

$env:CODEX_HOME

1. Check global instructions and AGENTS.md / AGENTS.override.md along the working-directory path. The default combined limit is 32 KiB.
2. After editing, start a new session and ask Codex to summarize loaded rules. Verify the working directory and CODEX_HOME.

printenv CODEX_HOME

$env:CODEX_HOME

1. Compare versions and all command paths. Check for overlapping npm, Homebrew and standalone installations.
2. Identify the main installation and update that one. For npm EACCES, check directory ownership rather than blindly reinstalling with sudo.

codex --version
command -v codex
type -a codex

codex --version
Get-Command codex -All
where.exe codex

1. Fully quit and reopen the affected client. Update it and test a fresh thread.
2. Record the CLI comparison, client version and timestamp. For an unresponsive Windows extension, check native runtimes.

codex doctor --summary

1. For sandbox startup failures, restart Codex and follow official guidance for elevated/unelevated modes and .sandbox/sandbox.log.
2. For an unresponsive extension or missing DLL, check C++ Build Tools and the x64 Redistributable. Do not share .sandbox-secrets.

codex doctor --summary

1. Setup can access the internet to install dependencies. Agent internet access is off by default; enable it as needed in environment settings.
2. Secrets are setup-only. A normal export does not persist across shells. Configure non-sensitive variables in the environment; never persist secrets in the repository.