OpenAI Codex can break in a few different ways: a sign-in loop, a usage limit message, a missing model, or a sandbox that blocks every command. Most of these have a quick fix once you know which part is failing.
This guide covers the Codex CLI, the Codex app and the IDE extension as of November 20, 2026. It includes the newest changes, like the --trust flag, GPT-6.2 models and the diagnostic ZIP.
- First check: status.openai.com has a Codex group (Codex Web, Codex API, CLI, VS Code extension).
- Update first: run
codex updateor reinstall. The latest CLI is 0.170.0 (November 18, 2026). - Sign-in loops: run
codex logout, thencodex login --device-authon SSH or headless machines. - Usage limits: check
/statusor/usage. Plus has a 5-hour window plus a weekly limit. - codex exec ignores your MCP servers: since CLI 0.169.0 untrusted folders keep project config off. Add
--trust. - Need help from OpenAI: run
/feedbackand press Ctrl+S to save a diagnostic ZIP.
Quick checks before anything else
Many “Codex is broken” moments are an outage or an old build. Run these four checks first. They take about two minutes.
- Check the status page. Open status.openai.com. The Codex group lists Codex Web, Codex API, CLI and VS Code extension. “Codex in ChatGPT Desktop” sits under the ChatGPT group.
- Check your version. Run
codex --version. If it is older than 0.170.0, update before you debug anything else. - Check your sign-in. Run
codex login status. It prints the active login mode and exits with 0 when you are signed in. - Run the doctor. Run
codex doctorfor a local report on runtime, auth, network and MCP. Add--summaryfor a short view.
Tip: If a feature works in the CLI but not in the app, they may run different Codex versions. On a Mac, compare codex --version with /Applications/Codex.app/Contents/Resources/codex --version.
Codex errors and fixes at a glance
Find your symptom in the left column. Each row links to a deeper section below.
| Symptom or error | Likely cause | Fastest fix |
|---|---|---|
| Browser login never finishes, or loops | Localhost callback on port 1455 is blocked, or you are on SSH | codex login --device-auth |
| Codex logs you out and exits right away | Credentials do not match forced_login_method or the forced workspace |
Sign in with the account or method your admin set |
| Keyring error at sign-in | cli_auth_credentials_store = "keyring" with no OS keyring |
Set it to auto or file |
| “Usage limit reached” | 5-hour or weekly allowance used up | Check /usage, wait for the reset, or use credits |
| “Model requires a newer version of Codex” | Old CLI or app build | Update, then pick the model again with /model |
| GPT-6.2 missing from the picker | Old build, or Enterprise/Edu admin has not enabled it | Update, or ask your workspace admin |
| Every command asks for approval, or Codex is read-only | Folder not trusted, or a :read-only profile |
Trust the folder with /permissions |
codex exec ignores project config and MCP servers |
Untrusted folder (CLI 0.169.0 change) | Add --trust |
| MCP server “timed out” at startup | Slow server, bad command path, missing env vars | Raise startup_timeout_sec |
npm install or curl fails inside Codex |
Network is off by default in the sandbox | Set network_access = true |
| TLS or certificate errors behind a company proxy | Private root CA | Set CODEX_CA_CERTIFICATE to your PEM bundle |
| Windows “Error 1385” | Windows denies the logon type for sandbox users | Ask IT for logon rights, or use unelevated for now |
| Ubuntu 24.04 user namespace warning | AppArmor blocks bubblewrap | Load the bwrap-userns-restrict AppArmor profile |
Fix sign-in and auth loops
Codex supports three sign-in types. ChatGPT sign-in uses your plan. API key sign-in bills at standard API rates. Codex access tokens are for Enterprise automation.
The CLI and the IDE extension share one login cache. It lives in ~/.codex/auth.json or in your OS credential store. So a broken login in one often breaks the other too.
Reset a stuck login
- Sign out. Run
codex logoutto clear the stored credentials. - Sign in again. Run
codex loginand finish the browser flow. - Use device code if the browser fails. Run
codex login --device-auth, open the link and enter the one-time code. You may need to enable device code login in ChatGPT security settings first. - Confirm it worked. Run
codex login status. - Read the log if it still fails. Open
codex-login.login your Codex log directory.
Sign in on SSH, servers and containers
The browser flow sends you back to a localhost callback on port 1455. On a remote machine that callback cannot reach your laptop browser. You have three options:
- Device code (preferred):
codex login --device-auth. Since CLI 0.169.0 this also works for supported gateways over SSH. - Port forwarding: connect with
ssh -L 1455:localhost:1455 user@remote, then runcodex loginin that session. - Copy the cache: sign in on a machine with a browser, then copy
~/.codex/auth.jsonto the same path on the server.
Warning: Treat auth.json like a password. It holds access tokens, so never commit it or paste it into a chat.
Other sign-in causes
- Wrong account or workspace: if an admin sets
forced_login_methodorforced_chatgpt_workspace_id, Codex logs out and exits when your login does not match. - Keyring missing: set
cli_auth_credentials_storetoauto. It falls back toauth.jsonwhen no keyring exists. - API key sign-in: pipe the key in with
printenv OPENAI_API_KEY | codex login --with-api-key. - Other sign-in options: since CLI 0.167.0, API key and cloud provider options sit under “Sign in another way.”
“Usage limit reached” and how resets work
This message means your plan allowance for Work and Codex is used up. It is not a bug. Codex and Work share usage, so heavy Work chats also drain your Codex budget.
How the limits are shaped
- Plus: a 5-hour window plus a weekly limit.
- Pro 100, Pro 200 and Pro 500: a weekly limit with no 5-hour window.
- Model cost: bigger models use more. GPT-6 Astra gives far fewer messages per window than GPT-6 Luna.
- Speed modes: Fast and Ultrafast burn your allowance faster than Standard.
For the full plan table and message ranges, see my ChatGPT and Codex usage limits guide.
Check what you have left
- In the CLI: type
/statusto see session config and token usage. - Account view: type
/usage. It shows account token usage and lets you use a rate-limit reset if you have one. - In the app: open Settings, then Usage, to see the meter.
Paid instant resets
Plus and Pro personal accounts may see a “Buy an instant reset” button next to the usage meter. It restores both the 5-hour and weekly usage right away.
- It does not add usage: it pulls your normal weekly allowance forward.
- Your reset date moves: the next weekly reset lands 7 days after your first request after the reset.
- No banking: you cannot save or schedule a paid reset, and purchases are generally non-refundable.
- Not on every plan: Free, Go, Business, Enterprise and Edu are excluded.
Note: Some users report the app saying they hit the limit while /status shows plenty left. Restart the app and sign out and in. If it persists, send a /feedback report with the session ID.
Model not available (GPT-6.2)
OpenAI released GPT-6.2 Astra and GPT-6.2 Sol on November 17, 2026. Both are in the Codex app and CLI. Astra is meant for the hardest projects and Sol for everyday coding.
If they do not show up, or you see “requires a newer version of Codex”, work through this list:
- Update Codex. New models often need a newer build. Run
codex updateor reinstall. - Pick the model again. In the CLI type
/model. In the app use the model picker. In a script, pass-m gpt-6.2-sol. - Check your config. The
modelkey in~/.codex/config.tomlmust name a model your account can use. A typo there breaks every session. - Ask your admin. On Enterprise and Edu, admins must enable the models in workspace settings first.
- Start a fresh chat. Resuming an old session that used a different model has caused this error before.
Ultrafast has its own rules. Pro $200 gets it with Sol only. Pro $500 gets it with both models. API users can read my GPT-6.2 API migration guide.
Sandbox, approval and permission profile errors
The sandbox decides which files and network resources commands can touch. The approval policy decides when Codex stops to ask you. Most “Codex can’t edit my files” reports come from these two settings.
Sandbox modes and flags
read-only: Codex can read files but cannot edit or run commands without approval.workspace-write: edits and routine commands inside the workspace. This is the default low-friction mode.danger-full-access: no sandbox limits. Use it only when you really want full access.
Set these per run with --sandbox (or -s). Set approvals with --ask-for-approval, which takes on-request or never. The old on-failure value is deprecated and untrusted is no longer supported.
Permission profiles (beta)
Permission profiles are the newer way to set access. CLI 0.170.0 updated the sandbox docs to explain them. The built-in profiles are:
:read-only: read-only local commands.:workspace: writes inside workspace roots and temp folders.:danger-full-access: no local sandbox limits.
default_permissions = ":workspace"
Warning: Do not mix default_permissions with sandbox_mode. If sandbox_mode or --sandbox appears anywhere, Codex uses the older sandbox settings and quietly ignores your profile.
Common sandbox causes
- Untrusted folder: Codex may start in read-only until you trust the folder through the first-run prompt or
/permissions. - Protected paths:
.git,.codex,.agentsand.awsstay read-only even inworkspace-write. - Lost restrictions: CLI 0.170.0 fixed child threads and permission updates losing sandbox rules. Update if you saw odd behavior.
- Linux: install
bubblewrap. Withoutbwrap, Codex needs unprivileged user namespaces. - Ubuntu 24.04: install
apparmor-profilesandapparmor-utils, copybwrap-userns-restrictto/etc/apparmor.d/, then load it withapparmor_parser -r.
Type /debug-config to print which config layer set each value. It is the fastest way to find a stray sandbox_mode line.
codex exec in an untrusted folder
CLI 0.169.0 (November 13, 2026) changed how codex exec treats new folders. In an untrusted directory, it now keeps project config and MCP servers disabled, even with --sandbox workspace-write.
So a CI job or script that worked last week may suddenly ignore your .codex/config.toml and its MCP tools. The fix is one flag:
codex exec --trust "run the test suite and fix failures"
codex review --trust
--trust saves project trust for that folder, so later runs load project config. Only use it on code you trust, because project config can start MCP servers and change behavior.
- Not a Git repo: add
--skip-git-repo-checkfor one-off folders. - Mark a folder untrusted on purpose: set
trust_level = "untrusted"under[projects."/path/to/project"]in your user config.
MCP server failures
The Codex app, CLI and IDE extension share MCP config in ~/.codex/config.toml. Project-level MCP servers in .codex/config.toml only load for trusted projects.
- Confirm the server exists. Run
codex mcp list. Inside a chat, type/mcpto see what is connected. - Raise the startup timeout. The default
startup_timeout_secis 10 seconds. Slownpxservers often need 30 or more. - Raise the tool timeout. The default
tool_timeout_secis 60 seconds. Raise it for long-running tools. - Check the command and env. A wrong path or missing API key in
envmakes the process exit before it connects. - Isolate a bad server. Set
enabled = falseon it without deleting the config. - Fix OAuth. Run
codex mcp login <server-name>. On a headless box add--no-browser, open the URL and paste the redirect back.
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 120
If a server is marked required = true, Codex will not start when that server fails. CLI 0.170.0 also fixed MCP OAuth races during login and logout. For good servers to try, see my best MCP servers list.
Network and proxy errors
By default, Codex runs local commands with network access turned off. So npm install, pip install or curl fail inside the sandbox even when your machine is online.
Allow network for commands
[sandbox_workspace_write]
network_access = true
With permission profiles, set network.enabled = true in the profile instead. Domain allow and deny rules only apply when features.network_proxy is on.
Company proxies and certificates
- Private root CA: set
CODEX_CA_CERTIFICATEto your PEM bundle beforecodex login. Codex falls back toSSL_CERT_FILE. - System proxy: since CLI 0.167.0 you can opt into macOS or Windows system proxy settings from
/experimental. - Connectivity test: run
codex doctor --network-only. It checks config, the network setup, and provider and WebSocket connections.
Note: The Codex network proxy does not govern web search, connectors, MCP servers or Codex service traffic. An MCP server that cannot connect is a separate problem from sandbox network rules.
Windows sandbox problems
In PowerShell, Codex uses a native Windows sandbox. In WSL2 it uses the Linux sandbox. There are three Windows modes:
| Mode | What it needs | When to use it |
|---|---|---|
mxc |
Windows 11 24H2 (build 26100.9278) or 25H2 (build 26200.9278) or later | Recommended. No admin setup or extra accounts. |
elevated |
Admin-approved setup | Preferred fallback on older Windows |
unelevated |
Nothing extra | Last resort. Weaker network isolation. |
Fix common Windows errors
- Error 1385: Windows denies the logon type sandbox users need. Ask IT for the logon rights, or set
windows.sandbox = "unelevated"for now. - Setup fails: usually a declined UAC prompt or a policy that blocks local users or firewall changes. Retry and accept the prompt.
- “Everyone” write warning: remove broad write access from the listed folders, then restart Codex.
- IDE extension frozen: install the Visual Studio Build Tools (C++ workload) and the x64 Visual C++ Redistributable, then fully restart VS Code.
- Quoted cmd.exe paths: CLI 0.169.0 fixed quoted
cmd.exepaths and PowerShell sessions with an unreadable parent folder.
To test MXC (CLI 0.162.0 or later), run this from your project folder. It should print MXC_OK.
codex -c windows.sandbox=mxc sandbox --include-managed-config --permission-profile :workspace -- cmd.exe /d /c echo MXC_OK
Sandbox logs live in CODEX_HOME/.sandbox/sandbox.log. Never share the .sandbox-secrets folder.
Update or reinstall Codex
Many bugs disappear after an update. Codex ships CLI releases several times a week. Use the same method you installed with.
| Install method | Install or update command |
|---|---|
| Built-in self-update | codex update |
| macOS and Linux installer | curl -fsSL https://chatgpt.com/codex/install.sh | sh |
| Windows installer (PowerShell) | powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex" |
| npm | npm install -g @openai/codex |
| Homebrew | brew upgrade --cask codex (install with brew install --cask codex) |
- Two installs fighting: if
codex --versiondoes not change after an update, you may have both npm and Homebrew copies. Remove one. - Codex app: update from the app itself. Since app 26.1106, it resumes eligible local chats from the past 24 hours after a crash.
- IDE extension: update it from your editor’s extensions panel, then restart the editor.
New to the tools? My OpenAI Codex guide covers setup for each surface.
Save a diagnostic ZIP and report a bug
When nothing works, give OpenAI a clean report. CLI 0.169.0 added a local diagnostic ZIP you can save even when uploads are disabled.
- Open the report editor. In the Codex CLI, type
/feedback. - Save the ZIP. Press Ctrl+S in the report editor to save the diagnostic ZIP locally.
- Add a doctor report. Run
codex doctor --jsonfor a redacted, machine-readable report. - Review before sharing. Check logs for secrets. Session files live in
~/.codex/sessions. - File the issue. Search the GitHub issues for openai/codex first, then open a new one with your version, OS and the ZIP.
In the Codex app, type / in the composer to send feedback. You get a session ID to share with OpenAI. On macOS the app logs are in ~/Library/Logs/com.openai.codex/.
Troubleshooting: still not working
These are the cases that slip past the steps above.
- Chat looks stuck: check for a pending approval prompt first. Then run
git statusor start a new chat with a smaller prompt. - Projects vanished from the app sidebar: app 26.1106 fixed account switching that hid projects. Update, then re-add the folder.
- History or resume shows nothing: CLI 0.168.0 filters history by the signed-in ChatGPT account. Sign in with the account that made those chats.
- “Approve for me” missing: update the app and check the permissions menu. Look for
features.guardian_approval = falsein your config. - Side chat panel not showing: it needs the opt-in
features.tui_workspace. See my Codex CLI side chats guide. - Windows MCP servers block file access: CLI 0.168.0 fixed idle local MCP servers blocking filesystem I/O. Update.
- Settings ignored in a project file: keys like
model_provider,profileandnotifyare ignored in project.codex/config.toml. Move them to your user config.
codex doctor, and check status.openai.com. Those three steps solve or explain most failures.Frequently Asked Questions
Why does Codex keep asking me to sign in?
Usually the localhost callback on port 1455 is blocked, or your cached login in ~/.codex/auth.json is broken. Run codex logout, then codex login --device-auth.
When does my Codex usage limit reset?
Plus has a 5-hour window plus a weekly limit, while Pro plans have only a weekly limit. Type /usage or open Settings, then Usage, to see your reset times.
Why can’t I see GPT-6.2 in Codex?
Your Codex build is likely too old, or your Enterprise or Edu admin has not enabled it. Update Codex, then choose the model with /model.
What does the --trust flag do in codex exec?
It saves project trust for the current folder. Since CLI 0.169.0, codex exec keeps project config and MCP servers off in untrusted folders until you pass it.
Why can’t Codex install packages or reach the internet?
Network access is off by default for local commands. Set network_access = true under [sandbox_workspace_write], or enable network in your permission profile.
Is Codex down right now?
Check status.openai.com. It lists Codex Web, Codex API, CLI and VS Code extension as separate components.
Should I use WSL or native Windows for Codex?
OpenAI recommends the native Windows sandbox by default. Choose WSL if you need Linux tools or your workflow already runs in WSL2.
Sources
- Codex changelog (CLI 0.166.0 to 0.170.0, app releases)
- Codex authentication docs
- Codex config reference
- Codex sandboxing docs
- Codex permission profiles
- Codex agent approvals and security
- Codex MCP docs
- Codex native Windows sandbox
- Codex CLI command line options
- Codex CLI install and update
- Codex app troubleshooting
- GPT-6.2 Astra and Sol announcement
- OpenAI Help: paid weekly Work and Codex resets
- OpenAI status page



