Codex process is not available

The app-server started, then died. Usually an unknown feature key, an expired OAuth grant, or a plugin manifest violation — with the issues tracking each.

Last reviewed 2026-08-04 · verified against the pingdotgg/t3code repo

Codex process errored: Codex process is not available
Codex app-server process exited unexpectedly (code=unknown, signal=SIGTRAP)
Codex app-server process exited with code 1 and signal null

Different wording, same underlying event: the app-server started, then died. That distinguishes it from failed to start, where it never launched at all — and the distinction matters, because the causes are completely different.

Most reports come from the VS Code extension, but the app-server is shared, so the same crashes surface in other clients.

Which cause is yours?#

Work down this table. The distinguishing symptom is the useful column.

1. Unknown feature keys#

The most-reported cause, and the most frustrating, because you usually didn't set the key.

Two documented instances:

ignoring invalid experimental feature enablement keys: apps_mcp_path_override
codex_features: unknown feature key in config: thread_tools

The app-server receives a feature key it doesn't recognise and crashes instead of ignoring it. In #29140 the reporter found thread_tools referenced nowhere in their local config — the strong suspicion is a server-side feature flag rollout reaching clients whose app-server build doesn't know the key yet. In #30378 the crash persisted even with the key absent from config.toml.

The tell in #29140 is diagnostic: plain conversational prompts worked, anything requiring a tool call crashed. If that matches your experience, this is your cause.

What to try:

# inspect your config for experimental keys
notepad $env:USERPROFILE\.codex\config.toml

# macOS / Linux
cat ~/.codex/config.toml

Remove any experimental or feature-flag entries you don't specifically need, then update — a newer app-server is more likely to recognise a newly rolled-out key:

npm i -g @openai/codex@latest
codex --version

2. Authentication failure#

From #29568, on macOS:

OAuth token refresh failed: Server returned error response: invalid_grant: Grant not found
Transport channel closed, when Auth(AuthorizationRequired)
Codex app-server process exited unexpectedly (code=unknown, signal=SIGTRAP)

A token refresh fails, the transport closes, the process exits. In that report it was triggered by interrupting a task while entering a prompt.

What to try:

codex login

Re-authenticating clears a stale grant. Restarting the extension restores function temporarily, which is a good confirmation that this is your cause rather than a feature-key crash.

3. A plugin manifest violation#

A secondary finding in #29140, worth knowing because it is entirely invisible otherwise: a bundled plugin's plugin.json exceeded the 128-character limit for defaultPrompt[0], and instead of omitting the field, the process became unavailable.

The reported path:

~/.codex/.tmp/plugins/plugins/ngs-analysis/.codex-plugin/plugin.json

If you have plugins installed, try disabling or removing recently-added ones and restarting. A single malformed manifest field can take down the whole app-server.

General recovery#

If you can't identify which cause is yours, this order clears the most ground:

# 1. kill any surviving process
ps aux | grep codex          # macOS / Linux
kill -9 <pid>

tasklist | findstr codex     # Windows
taskkill /PID <pid> /F

# 2. update
npm i -g @openai/codex@latest
codex --version

# 3. re-authenticate
codex login

# 4. confirm Codex works standalone, outside any editor or GUI
codex

Step 4 is the one that matters. If a plain codex session works but your editor extension or GUI still fails, the problem is in that client's integration, not in Codex — report it there. If plain codex also fails, it is a Codex problem and belongs on the openai/codex tracker.

Where to check for your exact variant#

This error string spans several distinct bugs. Before filing a new report, check whether yours is already covered:

Include your Codex version, OS, client and the full log line — without those the first reply will just ask for them.

If you're here because of T3 Code#

T3 Code runs codex app-server as a subprocess, so a crashing app-server ends a T3 Code session mid-run. Confirm codex works on its own first — T3 Code cannot keep a crashed subprocess alive.

FAQ#

What does "Codex process is not available" mean?#

The Codex app-server launched and then exited, so the client has nothing to talk to. It differs from a startup failure, where the process never launched — and the causes are different, most often an unrecognised feature key, an expired auth grant, or a malformed plugin manifest.

Why does Codex crash only when it tries to use a tool?#

That pattern points to an unknown feature key such as thread_tools. Plain conversation doesn't exercise the code path, but any tool call does, and the app-server crashes rather than ignoring the unrecognised key.

How do I fix the app-server crashing on Windows?#

Check %USERPROFILE%\.codex\config.toml for experimental feature keys and remove ones you don't need, update the CLI with npm i -g @openai/codex@latest, kill any surviving codex processes, and re-authenticate with codex login.

Is this a bug in Codex or in my editor extension?#

Run a plain codex session in a terminal. If that works and only your extension fails, it's the extension's integration. If plain codex also crashes, it's Codex, and the openai/codex tracker is the right place.

Can I fix an unknown feature key error myself?#

Not always. When the key arrives from a server-side rollout rather than your config file, no local change helps — it resolves when OpenAI rolls back the flag or ships a build that recognises it.