Codex Errors: 15 Symptoms Mapped to a Tested Fix (2026)
Every Codex error we have reproduced, matched to its cause and fix: app-server os error 3, couldn't load its resources, 401, usage limit, sandbox.
Ofox 
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.
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.0The 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.
What is almost never the cause?
Worth naming, because they absorb the most time.
Your API key. Rotating it fixes a Incorrect API key provided. It does nothing for Missing bearer or basic authentication in header, which means the key never left your shell, and nothing for a 429, which means the key worked.
Reinstalling. If codex is not on your PATH, reinstalling puts it back in the same place it already is. Find the prefix instead: npm prefix -g, then check whether <npm-prefix>/bin is in $PATH.
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?
- Because the Windows failures are almost all install-location failures, not Codex failures. The Microsoft Store build puts the binary under C:\Program Files\WindowsApps\ with a sandbox around it, so the launcher reads a manifest path that resolves to nothing and you get 'os error 3' or 'manifest entry is missing required path'. macOS and Linux failures cluster around PATH, Node version managers, and the Linux sandbox instead.
- What should I check before working through any Codex fix?
- Your version. Run
codex --versionfor 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
resetsAttimestamp 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/codexon 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 aboutconfig.tomlor a sandbox is a CLI problem.
