Codex "failed to start codex app-server" on Windows: Causes and Fixes (2026)

“failed to start codex app-server” on Windows: The 30-Second Diagnosis

You launched Codex Desktop on Windows. The window opens, or a tray icon appears, and then this:

failed to start codex app-server: The system cannot find the path specified. (os error 3)

Localized builds show the same thing in your language. German users see Das System kann den angegebenen Pfad nicht finden. (os error 3). The os error 3 code is the constant: it is Windows ERROR_PATH_NOT_FOUND.

Run these three checks in order. The first one that comes back wrong points at the fix.

# 1. Which Codex packages are actually installed?
Get-AppxPackage *Codex* | Select-Object Name, Version, InstallLocation

# 2. Does your profile path contain non-ASCII characters?
echo $env:USERPROFILE

# 3. Is there more than one Codex version on PATH?
$env:PATH -split ';' | Select-String 'Codex'

The single fact that saves the most time: the Codex CLI and Codex Desktop are separate programs. If codex --version works in a plain terminal but the Desktop app throws the app-server error, your account, your key, and your Codex install are all fine. You are hitting a Desktop shell bug, and you can keep shipping from the CLI while it gets fixed. That escape hatch is the last section of this article.

Every fix below is tied to a real, open issue in the openai/codex tracker as of 2026-07-16. No invented version numbers.

What the app-server Actually Is (and Why os error 3 Happens)

Codex Desktop is an Electron app. The window you see is a thin UI shell. The real work happens in a separate child process called the app-server: talking to the model, running Browser Use, executing a task. The shell spawns the app-server at startup and talks to it over a local socket.

os error 3 is raised at the moment the shell tries to spawn that child process and Windows cannot find the path to the executable it was told to run. Note what this is not: it is not a network error, not an auth error, not a rate limit. The failure happens before any request leaves your machine. The shell has a path string, that string does not resolve to a file, Windows returns ERROR_PATH_NOT_FOUND, and the shell surfaces it as failed to start codex app-server.

Codex Desktop (Electron UI shell)
        │
        │  spawn( <path-to-app-server> )   ← path resolved at install/launch
        ▼
   ┌─────────────────────────┐
   │  path is valid  ────────►│  app-server runs, chat + Browser Use work
   │                          │
   │  path is stale/wrong ───►│  os error 3  →  "failed to start codex app-server"
   └─────────────────────────┘

So every cause below is a variation on one theme: the path the shell resolved is wrong. It can be wrong because an old package version is still on PATH, because a non-ASCII character in your profile path broke resolution, because the Store sandbox will not let the shell execute the bundled binary, or because the binary is not where the shell expects it. Same symptom, four different roots.

When to Fix and When to Switch to the CLI

Before you spend an hour on the Desktop app, decide whether it is worth it.

Fix the Desktop app when

• You specifically need Browser Use or another in-app feature that only the Desktop app exposes.
• Your team standardized on the Desktop app and you want parity.
• The error appeared after an update and you suspect a stale-PATH regression (Fix 1 is a two-minute check).

Switch to the CLI instead when

• You mainly use Codex for coding in a terminal or editor. The CLI does everything the app-server does for that workflow, and it does not depend on the Electron shell at all.
• Your Windows username contains non-ASCII characters and creating a new user account is more disruptive than just using the CLI.
• You are on a locked-down machine where you cannot change Store-package permissions.

The stop rule

If you have run Fix 1 through Fix 4 and the app-server still will not start, stop debugging the app. Install the CLI (npm i -g @openai/codex), confirm codex --version prints a version, and work from there. The Desktop app is not a prerequisite for using Codex. Chasing an open Electron bug past the four fixes is a poor use of an afternoon.

The os error 3 Cluster: Open Issues as of 2026-07-16

Here is the map of what people are actually reporting, so you can match your exact error text to a root cause and a fix. Every issue below is OPEN.

If your error text does not exactly match one of these, read the closest match and treat its fix as the starting point. The os error 3 string itself is #20206 and #20048; the “Unable to locate the Codex CLI binary” wording is #28392 and #28031; the crash-after-launch (code=1) with a plugin WARN is #26440.

Fix 1: Stale PATH Pointing at an Old Package Version

This is the most common cause and the fastest to check. Codex updates ship as new Windows Store packages with a version-stamped folder name, for example OpenAI.Codex_26.422.8496.0_x64__2p2nqsd0c76g0. If an older package version is still referenced on PATH, the shell can resolve the app-server path against a folder that no longer contains the file it wants.

In #20206 the reporter noted exactly this: after a restart, PATH pointed to the current package version only, but before the restart there had been an older package version on PATH as well. Cleaning that up is step one.

# List every Codex package still installed
Get-AppxPackage *Codex* | Select-Object Name, Version, PackageFullName

# Look for stale WindowsApps entries on PATH
$env:PATH -split ';' | Select-String 'OpenAI.Codex'

If you see two or more different version strings, remove the old ones:

# Remove the Store package entirely, then reinstall a single clean copy
Get-AppxPackage OpenAI.Codex | Remove-AppxPackage

Reinstall from a single source (the Store, or better, the npm/official installer covered in Fix 4). After reinstalling, open a new terminal (PATH changes never apply to already-open shells) and relaunch Codex Desktop.

Restart alone is not a fix here. It clears a stale in-memory PATH, but if the underlying reason the path is wrong is structural (Fix 2, 3, or 4), the error comes right back. #20206 is the proof: a full Desktop restart did not resolve it.

Fix 2: Non-ASCII Characters in Your Windows Profile Path

Codex writes and reads state under your profile directory: C:\Users\<you>\.codex\.... If <you> contains non-ASCII characters (Scandinavian letters like å ö ø, German umlauts, accented Latin, or CJK), path resolution can fail in a way that surfaces as os error 3. This is a long-standing failure mode for Windows tooling that assumes ASCII paths, and Codex’s app-server spawn is not immune.

Check first:

echo $env:USERPROFILE
# C:\Users\Håkon\...   ← the å is the problem

If your profile path is clean ASCII, this is not your cause; skip to Fix 3. If it contains non-ASCII characters, the cleanest isolation is a new local user with an ASCII-only name:

Settings → Accounts → Other users → Add account
→ create a local account with an ASCII-only username (e.g. "dev")
→ sign in as that user
→ install and run Codex there

If Codex Desktop starts cleanly under the ASCII user, you have confirmed the cause. From there you have two durable options: keep a dedicated ASCII profile for Codex, or drop the Desktop app and use the CLI, which you can point at any working directory regardless of your username. Renaming an existing Windows user’s profile folder is risky and not worth it; create a fresh account instead.

Fix 3: Microsoft Store Sandbox Blocks the Bundled codex.exe

Store-packaged apps install under C:\Program Files\WindowsApps\, a directory that is read-only and access-restricted for most processes. In #28031, the bundled codex.exe exists inside the package but cannot be executed, because the OS denies access, so the app-server never starts. The reporter had tried app reset, uninstall/reinstall, and clearing CODEX_CLI_PATH, and the failure persisted.

Confirm what you have:

# Where did the package land, and is the binary there?
$pkg = (Get-AppxPackage *Codex*).InstallLocation
Get-ChildItem $pkg -Recurse -ErrorAction SilentlyContinue |
  Where-Object { $_.Name -match 'codex' } |
  Select-Object FullName, Length

If the binary is present under WindowsApps but the app still fails with an access-denied flavor of the error, do not fight the sandbox. The reliable path is to stop relying on the Store-bundled binary entirely:

# 1. Remove the Store package
Get-AppxPackage OpenAI.Codex | Remove-AppxPackage

# 2. Install the CLI outside the sandbox, into a normal user-writable location
npm i -g @openai/codex

# 3. Confirm it runs
codex --version

Now the codex binary lives under your npm global prefix (a normal, executable location), not inside the Store sandbox. If you still want the Desktop app, point it at this binary with CODEX_CLI_PATH (see Fix 4). If you do not, just use the CLI.

Fix 4: “Unable to locate the Codex CLI binary” (Missing or Mislocated Binary)

The Electron shell expects to find the Codex CLI at bin/codex inside its own resources, or at the path in the CODEX_CLI_PATH environment variable. When neither is satisfied you get the explicit message from #28392 and #28031:

Codex failed to start.

Unable to locate the Codex CLI binary. Set CODEX_CLI_PATH or
ensure the Electron resources include bin/codex.

Related reports (#25671, #25886) show the same class of failure with different wording: “Codex app-server is not available”, “Unable to find Electron app at …”, or a websocket that closes with code=4294967295. All are cases where the shell cannot reach a working app-server binary.

The fix is to give the shell a binary it can find. Install the CLI from a source that lands in a normal, executable location:

# Option A: npm (recommended; needs Node 16+ on PATH)
npm i -g @openai/codex
where.exe codex          # note the resolved path, e.g. C:\Users\you\AppData\Roaming\npm\codex

# Option B: winget
winget upgrade OpenAI.Codex
# or, if not yet installed:
winget install OpenAI.Codex

Then point Codex Desktop at that binary by setting CODEX_CLI_PATH to the resolved path:

# Use the path where.exe printed above
[Environment]::SetEnvironmentVariable(
  "CODEX_CLI_PATH",
  "$env:APPDATA\npm\codex.cmd",
  "User"
)

Close every terminal and relaunch the app so it picks up the new User-scope variable. If setting CODEX_CLI_PATH still does not get the app-server up, which several reporters have seen, the app has a deeper resolution bug on your machine, and the CLI-direct path in the Fallback section is your answer.

Fix 5: A Cached Plugin Manifest Crashes the app-server

A different failure shape: the app does start, then the app-server exits a few seconds later. In #26440, the app-server crashes with code=1 while loading a cached plugin manifest. The logs show a WARN that a plugin’s interface.defaultPrompt[0] exceeds Codex’s 128-character limit (the offending cached manifest held a ~313-character string), and the app-server exits unexpectedly. This happens in both Codex Desktop and Codex in VS Code, and it can fire even when the chat is idle. The plugin the reporter hit was not even enabled in config.toml.

If your error is a crash-after-launch with code=1 rather than the clean os-error-3 at startup, clear the plugin cache:

# Back up, then remove the cached plugin tree under your profile
Move-Item "$env:USERPROFILE\.codex\.tmp\plugins" `
          "$env:USERPROFILE\.codex\.tmp\plugins.bak" -ErrorAction SilentlyContinue

Relaunch Codex. It regenerates the plugin cache from scratch. If a specific plugin’s manifest is what tips it over the 128-character limit, keeping that plugin out of your config prevents the cache from re-including it. This is a distinct root cause from the path errors above. Do not run Fix 1 through Fix 4 for a code=1 plugin crash; they will not touch it.

Common Failure Patterns on Windows Codex Desktop

Pulling the cluster together, here is what recurs and how the shapes differ. Match the exact string you see.

Two takeaways from the pattern. First, “app-server won’t start” is not one bug. It is at least four (path, sandbox, missing binary, plugin crash), each with its own issue. Second, the Store package is over-represented across the cluster. If you installed from the Microsoft Store and you are stuck, moving to the npm or official-installer CLI removes a whole category of these at once.

Read the Logs Before You Change Anything

The error dialog gives you one line. The logs give you the path Codex actually tried to spawn, which is the piece that tells you which of the causes above you have. Two minutes here saves you from running fixes for the wrong root cause.

Codex writes state and logs under your profile. Start there:

# Inspect the Codex state directory
Get-ChildItem "$env:USERPROFILE\.codex" -Recurse -ErrorAction SilentlyContinue |
  Select-Object FullName, Length, LastWriteTime |
  Sort-Object LastWriteTime -Descending |
  Select-Object -First 20

Look at the most recently written files first; the failure you just triggered is at the top. When the log names a concrete path in the os-error-3 message, compare it against what is actually installed:

# What path does the app think the app-server lives at, vs. what is on disk?
Get-AppxPackage *Codex* | Select-Object Name, Version, InstallLocation
Test-Path "C:\Program Files\WindowsApps\OpenAI.Codex_*\app\resources\codex.exe"

If Test-Path returns False, the binary the shell is looking for is genuinely not there (Fix 4). If it returns True but the app still fails with an access-denied flavor, the file exists and the sandbox is blocking execution (Fix 3). If two package versions show up, you have the stale-PATH case (Fix 1). This one check disambiguates three of the five causes.

For the crash-after-launch case, the useful signal is the CLI log line rather than the dialog. In #26440 the log printed the exact plugin manifest path and the reason (prompt must be at most 128 characters) right before the code=1 exit. Grep the state directory for the WARN:

# Find the plugin manifest that is crashing the app-server
Select-String -Path "$env:USERPROFILE\.codex\*.log" -Pattern "defaultPrompt|exited unexpectedly|os error 3" -ErrorAction SilentlyContinue

The rule of thumb: an os-error-3 at startup is a path problem, a code=1 exit seconds after the window renders is a plugin/manifest problem, and a websocket-closed message is the app-server dying before it can hand off to the UI. Match the log line to the cluster table, then run only the fix for that root cause.

This is the decision flow in one picture. Start at the top with what your log or dialog actually shows:

 app-server error
        │
        ├─ "os error 3" at startup ──────────┐
        │                                     │
        │   two package versions on PATH? ──► Fix 1 (remove stale version)
        │   non-ASCII in $env:USERPROFILE? ─► Fix 2 (ASCII profile)
        │
        ├─ "Unable to locate the CLI binary"
        │        │
        │        ├─ binary present but blocked ► Fix 3 (Store sandbox)
        │        └─ binary absent ────────────► Fix 4 (install + CODEX_CLI_PATH)
        │
        ├─ "code=1" + defaultPrompt WARN ────► Fix 5 (clear plugin cache)
        │
        └─ none apply, `codex --version` works ► Fallback (use the CLI)

The single branch that ends every path: if codex --version works in a terminal, you have a working Codex regardless of the Desktop app’s state. That is why the fallback is not a consolation prize; it is often faster than any of the five fixes.

Codex in VS Code shows the same error

The VS Code Codex extension launches the same app-server the Desktop app does, so the identical failures surface there. #26440’s plugin crash reproduces in both. If the extension throws the app-server error but your terminal codex is healthy, the fix is the same: the extension is hitting a Desktop-class bug, and running codex directly in the integrated terminal bypasses it. Do not reinstall the extension expecting a different result; the app-server code is shared.

When the Desktop App Won’t Start: Keep Working from the CLI

If you have walked the fixes and the Desktop app still refuses, stop. You do not need it. The Codex CLI is a standalone program that does not depend on the Electron shell or its app-server, and it runs on native Windows.

Free / individual: run the CLI directly

Install once, run in any terminal:

# Needs Node 16+ on PATH
npm i -g @openai/codex
codex --version
codex

If codex --version prints a version and codex opens the interactive session, you have full Codex functionality for coding work: no app-server, no Electron, none of the Windows Desktop failure modes above. This is the answer for #20048’s exact situation, a working npm CLI while the Desktop app throws os error 3. Use the CLI, file/track the Desktop bug, and move on.

Paid / team: pin one clean install and skip the Store

Teams get bitten repeatedly by the Store package because every machine hits the sandbox and stale-version problems independently. Standardize on the npm CLI at a pinned version so every developer and CI runner is identical:

# On every dev machine and CI runner
npm i -g @openai/codex
codex --version   # confirm the same version everywhere

Pinning removes the “works on my machine” spread that the Store’s per-machine packaging creates. If someone still wants the Desktop UI, they can point it at this CLI with CODEX_CLI_PATH (Fix 4) rather than relying on the bundled binary.

Any tier: route the CLI through an OpenAI-compatible provider

If your reason for opening Codex is to get coding work done and you do not care whether the request goes to OpenAI directly, you can point the Codex CLI at an OpenAI-compatible endpoint through a gateway. That decouples “can I run Codex” from “is the Desktop app healthy” entirely: the CLI talks to the gateway, the gateway talks to whichever model you configured.

Ofox exposes a single https://api.ofox.ai/v1 base URL that the Codex CLI accepts. When the Desktop app is down on Windows, you configure the CLI once and keep shipping against your chosen model.

# ~/.codex/config.toml  (on Windows: C:\Users\<you>\.codex\config.toml)
model_provider = "ofox-codex"

[model_providers.ofox-codex]
name = "Ofox"
base_url = "https://api.ofox.ai/v1"
env_key = "OFOX_API_KEY"
wire_api = "responses"

Codex needs wire_api = "responses". Current Codex removed the older wire_api = "chat" value; passing it fails at config-load time before any request goes out. A gateway that only implements /v1/chat/completions will not work, so confirm your gateway documents Responses API support and test with a real key before relying on it.

Two companion posts cover the surrounding CLI issues directly. If the CLI itself will not resolve on your PATH, start with the codex: command not found fixes. If the CLI works but the Desktop app hides custom models, see Codex Desktop Not Showing Custom Models.

How to Monitor the app-server Bug Status

This cluster is moving. New Codex versions ship roughly weekly, and fixes land per-issue rather than in one sweep. Before assuming an update fixes your case, check the specific issue that matches your error text.

Watch the exact issue that matches your error string, not the cluster in general. Use #20206 and #20048 for os error 3, #28392 and #28031 for the missing-binary wording, and #26440 for the plugin crash. Read the official Codex changelog before you update: look for the issue number or the word “app-server” in the notes rather than updating blind and hoping a random release helps. And keep the CLI as your baseline. Because it does not depend on the Desktop app-server, a working codex --version in a terminal means a broken Desktop app is an inconvenience, not a blocker.

Save this as codex-diag.ps1 and run it whenever the app-server error comes back. It collects every signal the fixes above key off, in one pass:

# codex-diag.ps1 : collect the signals the app-server fixes depend on
Write-Host "== Installed packages =="
Get-AppxPackage *Codex* | Select-Object Name, Version, InstallLocation

Write-Host "== Profile path (non-ASCII breaks path resolution) =="
$env:USERPROFILE

Write-Host "== Stale versions on PATH =="
$env:PATH -split ';' | Select-String 'OpenAI.Codex'

Write-Host "== CLI on PATH? (your fallback) =="
where.exe codex 2>$null; codex --version 2>$null

Write-Host "== Recent errors in the state dir =="
Select-String -Path "$env:USERPROFILE\.codex\*.log" `
  -Pattern "os error 3|exited unexpectedly|defaultPrompt|websocket closed" `
  -ErrorAction SilentlyContinue | Select-Object -Last 10

The output tells you which fix applies without guessing: two package versions means Fix 1, a non-ASCII profile means Fix 2, a present-but-blocked binary means Fix 3, an absent binary means Fix 4, and a defaultPrompt WARN means Fix 5. A working codex --version at the bottom means you can stop debugging and switch to the CLI right now.

FAQ

The frontmatter faq block holds the canonical answers. They cover what os error 3 means, the “Unable to locate the Codex CLI binary” wording, whether a restart fixes it, the non-ASCII username trap, whether you can keep working without the Desktop app, whether the bug is fixed yet, and how to clear old package versions from PATH.

References

• openai/codex#20206
• openai/codex#20048
• openai/codex#25671
• openai/codex#25886
• openai/codex#26440
• openai/codex#28031
• openai/codex#28392
• Codex CLI changelog
• ofox docs: Codex integration
• codex: command not found, 7 fixes
• Codex Desktop Not Showing Custom Models