TL;DR: Most Codex errors are misfiled. The message names the symptom, not the cause, so people spend an afternoon rotating an API key when the real problem is a Windows Store install path or a missing bubblewrap package. This page is the index: 15 failures we have reproduced, each mapped to the thing that is actually broken and to the page with the tested fix. Start with your version, then find your string.
Last updated 2026-08-31. Version numbers and issue states on this page were read from npm, GitHub and OpenAI’s own docs on that date.
For configuration rather than an error, go directly to config.toml paths and examples or custom providers and profiles. For an API model 404, use the model ID, access and endpoint checks. Match the actual error text before changing credentials or reinstalling.
What should you check before any Codex fix?
Three of the biggest error families in this list are regressions with a known fixed build. If you are on the broken build, the fix is the upgrade and nothing else on this page applies.
codex --version # CLI
npm view @openai/codex version # latest published: 0.151.0
The editor extension carries its own version, and it is the one that matters for the “couldn’t load its resources” family: the break landed in 26.803.41515 and the fix landed in 26.810.41047. AGENTS.md loading in symlinked workspaces was fixed in CLI v0.138. Upgrade first, reproduce second.
Which Codex are you running?
Five surfaces ship under the same name and they fail in different places. Getting this wrong is the most common reason a fix does not work.
| Surface | What it is | Where its errors come from |
|---|---|---|
| CLI |
@openai/codex, a Rust binary with an npm wrapper |
PATH, ~/.codex/config.toml, the sandbox, auth |
| Editor extension | the Codex panel in VS Code and forks | resource loading, the app-server handshake, the native host |
| Chrome extension | browser control, installed from the ChatGPT desktop app | native host version, permissions, browser support |
| ChatGPT mobile | Codex inside the phone app | nothing local; it is a remote session |
| Desktop app | the ChatGPT desktop client that hosts the above | model picker, model_catalog_json
|
If your error mentions resources, a native host, or an app-server, you are in extension territory even if you also use the CLI. If it mentions config.toml, a sandbox, or a provider, you are in CLI territory.
Which Codex error do you have?
Every string below is quoted as it appears. Find yours, then follow the link for the reproduction and the fix.
Why will Codex not install or start?
| Error message | What is actually wrong | Fix |
|---|---|---|
zsh: command not found: codex |
npm installed it somewhere not on your PATH, usually because of NVM, Volta, or a custom npm prefix -g
|
codex: command not found |
failed to start codex app-server (os error 3) |
Windows cannot resolve the path it was handed, most often a Microsoft Store install under WindowsApps\
|
failed to start codex app-server on Windows |
manifest entry is missing required path nodePath/resourcesPath |
the launcher read an install manifest whose recorded paths no longer exist | same page, fix 6 |
unable to locate the codex cli binary |
the extension is looking for a CLI that was never installed, or was installed under a different user | failed to start codex app-server on Windows |
Codex could not start the extension. Codex couldn't load its resources. |
the 26.803.41515 regression, which breaks five different ways behind one message |
couldn’t load its resources |
codex chrome native host is out of date |
the browser extension and the desktop app are on mismatched builds | couldn’t load its resources |
Windows deserves its own note, because a lot of advice still says WSL2 is mandatory. It is not. The project README gives Windows its own one-liner:
Run the following on Windows to install Codex CLI:
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
That installer needs no Node at all. WSL2 is a choice rather than a requirement, but the two paths get different sandboxes. Native versus WSL2 has the trade-off; the install guide has all the routes including the standalone installer that needs no Node at all.
Why can Codex not authenticate?
| Error message | What is actually wrong | Fix |
|---|---|---|
Missing bearer or basic authentication in header |
no key was sent at all, usually an env var that never made it into the shell Codex runs in | Codex CLI 401: 9 tested causes |
Incorrect API key provided |
a key was sent and rejected, which is a different problem with a different fix | Codex CLI 401: 9 tested causes |
| requests hang and then time out on connect | a PAC or WPAD corporate proxy that Codex does not discover, or a missing CA certificate | Codex behind a corporate proxy |
Nine failures return something a user reads as a 401, and only some of them are literally 401. Read the message body, not the status code.
Why has Codex run out of quota?
| Error message | What is actually wrong | Fix |
|---|---|---|
You've hit your usage limit |
a subscription window closed; the reset is a server-side resetsAt timestamp, not a clock rule |
Codex reset: when your limit clears |
429 Too Many Requests on a metered key |
rate limiting or a spend cap on the API side, which is a separate system from the subscription window | cap your spend with a drop-in API |
This is the single biggest source of Codex searches we see, and most of the advice online is wrong about it. There is no fixed number of days to wait, there are exactly two windows, and an earned reset is a credit you can redeem rather than a date you wait for. A 429 on a metered key is not the same event at all: for what the code means per provider, see LLM API error codes.
Why does Codex refuse to run commands or read your files?
| Error message | What is actually wrong | Fix |
|---|---|---|
command failed; retry without sandbox |
on Linux, bubblewrap is missing or cannot open the paths it needs; on any OS, sandbox_mode is stricter than the task |
command failed; retry without sandbox |
| AGENTS.md is ignored, no error at all | the workspace path traverses a symlink, on CLI builds before v0.138 | AGENTS.md not loading in symlinked workspaces |
The sandbox one has a trap worth knowing: Codex prints a bubblewrap warning whose match string does not exist on every distribution, so a broken sandbox can fail silently on some Linux installs. The fix page has the five-distribution test.
Why will your model or provider not appear?
| Error message | What is actually wrong | Fix |
|---|---|---|
| custom models missing from the Codex Desktop picker | the model_catalog_json bug; the picker has nothing to describe when the model is set inline |
Codex Desktop not showing custom models |
| an unknown model silently caps at 258K context | Codex falls back to a default context size for models not in its catalog | Qwen 3.8 Max in Codex CLI |
Pointing Codex at a provider other than OpenAI is a supported path, not a hack, but there are three places to do it and they behave differently. The config.toml reference is the full surface. The [model_providers] block is how you keep several providers side by side. The custom endpoint guide is the two-variable version if you only want one. One constraint that catches people: Codex only accepts wire_api = "responses" for custom providers, so a chat-completions-only gateway will not work no matter how the rest is configured.
Which changes need evidence first?
Changing API keys. For a rejected key, verify the selected provider, credential and account. For a missing-header error, inspect whether the client actually sends authentication. A 429 needs rate-limit or quota checks, not automatic key rotation.
Reinstalling. For a command-not-found error, inspect PATH and the installed binary before reinstalling. Installation damage and path configuration are different causes; use the logs to distinguish them.
An open GitHub issue. An issue still marked open does not mean the feature is missing. Codex issue #22638 asks for Chromium browser support and is still open, while the docs list five supported browsers and the feature shipped. Check the product, then the tracker.
How do you set Codex up from scratch?
If nothing is broken yet and you are here to configure rather than repair:
- Install it, on any of npm, Homebrew, the standalone installer, or a raw binary.
- Write a
config.tomland understand the three approval modes and three sandbox levels before you loosen either. - Point it at the model you actually want, whether that is an OpenAI model or something else through an OpenAI-compatible gateway.
- Learn the loop: AGENTS.md, plan mode, worktrees, and the seven mistakes that waste the first week.
Coming from somewhere else, the Claude Code migration maps all 12 config surfaces and names the one dead end. Choosing rather than migrating, Claude Code vs Codex vs Cursor vs DeepSeek TUI and OpenCode vs Codex CLI are the head-to-heads.
What about the browser, mobile and desktop surfaces?
The Chrome extension now covers Chrome, Edge, Brave, Opera and Vivaldi and installs from the ChatGPT desktop app. Codex on iPhone and Android is a remote session, so nothing about PATH or sandboxes applies there. Goal Mode and remote computer use is the long-running agentic mode and its own safety model.
References
Frequently Asked Questions
Why does Codex fail with a different error on Windows than on macOS?
Operating systems and installation methods use different paths, permissions and process launchers. On Windows, os error 3 points to a path lookup failure; inspect the actual executable path and application logs. Do not assume every Windows failure has the same cause.
What should I check before working through any Codex fix?
Your version. Run codex --version for the CLI and check the extension version in your editor. Several of the most-reported 2026 errors are regressions with a known fixed build: the 'couldn't load its resources' family was introduced in 26.803.41515 and fixed in 26.810.41047, and AGENTS.md in symlinked workspaces was fixed in CLI v0.138. Upgrading is the whole fix in those cases.
Is a Codex 401 always an authentication problem?
No. Nine distinct failures return something that looks like a 401, and they split into three groups that need different fixes: no key was sent at all ('Missing bearer or basic authentication in header'), a key was sent and rejected ('Incorrect API key provided'), and a key that is correct but carries a trailing newline from a shell export. The status code is the same; the message body is what tells them apart.
Does hitting the Codex weekly limit mean I have to wait a fixed number of days?
No. The reset is a server-side resetsAt timestamp attached to your account, not a clock rule you can compute, and there are only two windows (primary and secondary). You can read the actual timestamp rather than guessing, and an earned reset credit can be redeemed early.
Which Codex surface am I actually using?
There are five and they fail differently: the CLI (@openai/codex on npm, currently 0.151.0), the editor extension, the Chrome extension driven by the ChatGPT desktop app, Codex inside the ChatGPT mobile app, and the desktop app itself. An error about resources or a native host is an extension problem; an error about config.toml or a sandbox is a CLI problem.
Originally published on ofox.ai/blog.
Top comments (0)