"invalid transport in mcp_servers.codex_app" in Codex: why every chat fails and how to fix it
Back to the blog
Articlecodextroubleshootingwindowsmcpopenai

"invalid transport in mcp_servers.codex_app" in Codex: why every chat fails and how to fix it

MafraNovember 15, 20266 min read

You open Codex Desktop on Windows, pick a project, and send the first message. The chat never starts. The terminal or the UI hands you:

failed to load configuration: invalid transport
in `mcp_servers.codex_app`

You open config.toml looking for that server. It is not there. You never configured anything called codex_app. That is the point where most people start changing things they should not, reinstall the app, wipe .codex, and lose an afternoon.

The message is not about your configuration. It is about an internal component of the app itself that stopped being valid in the environment where the backend is running. There is one dominant cause, and it has a one-line fix.

Flowchart: every chat fails with invalid transport, confirm in the log, check whether the backend runs inside WSL, turn WSL off and, if it still fails, quit and relaunch the app
The path of the error: the internal server transport does not exist inside WSL, and that failure takes down the whole config load.

What is this message actually saying?

Codex Desktop ships an internal plugin, codex-app-tools@openai-bundled, that registers an MCP server named codex_app. That server is not your integration. It is what backs thread and subagent orchestration, with tools like create_thread, fork_thread and send_message_to_thread.

Its transport is declared like this, in %USERPROFILE%\.codex\plugins\cache\openai-bundled\codex-app-tools\0.1.3\desktop-mcp.json:

{
  "mcpServers": {
    "codex_app": {
      "command": "cmd.exe",
      "args": ["/d", "/s", "/c", "call", "./scripts/launch_codex_app_tools_mcp.cmd", "./server.mjs"],
      "cwd": ".",
      "enabled": true
    }
  }
}

Read the command line: cmd.exe. That is a transport that only exists on Windows. When the app backend runs inside WSL, whatever tries to spawn that process is a Linux binary, and it cannot resolve cmd.exe. The config loader rejects the server with invalid transport, and because the rejection is fatal, every thread/start returns -32600. It is not one broken chat, it is all of them.

How do you confirm it in two minutes?

Go to the app logs and look for two things: the error string and the line that shows which environment the backend is running in.

# Windows (PowerShell), logs for the Microsoft Store package
cd "$env:LOCALAPPDATA\Packages\[OI].Codex_2p2nqsd0c76g0\LocalCache\Local\Codex\Logs"
Select-String -Path *.log -Pattern "invalid transport","Spawning process inside WSL"

If both show up together, the diagnosis is closed. In issue #40910 of the official repo, the A/B test is exactly that: same app, same config.toml, same machine, only the WSL key flipped. With WSL on, 125 occurrences of the error across several sessions. With WSL off, none, and the message is sent and processed normally.

How do you fix it?

Open config.toml (it lives at %USERPROFILE%\.codex\config.toml) and turn off execution inside WSL:

runCodexInWindowsSubsystemForLinux = false

If the key already exists, just change the value. Quit the whole app, not just the window, and open it again. The fix is immediate and reliable, and it is what the issue reports as the solution that always works.

Watch out for a detail that trips people up: in the app this setting shows up as a toggle in preferences labelled "Run Codex in WSL". Changing it through the toggle or through the file has the same effect, but the app has to restart to re-read it. If you changed it and nothing happened, you probably only closed the window.

Why does disabling the plugin not work?

This is the step that burns the most time for anyone trying to solve it alone. The temptation is to disable the plugin that appears in the error:

[plugins."codex-app-tools@openai-bundled"]
enabled = false

It does not work. The server is still loaded and still fails, because it does not go through the normal plugin toggle. Issue #40910 records this explicitly. If you got here trying that route, you can stop trying.

What if you need WSL?

The honest answer here is that there is no supported fix so far. Turning WSL off solves the error, but it changes the execution environment: /mnt/... paths, MCP servers that only exist on Linux, and native toolchains stop applying. If your workflow depends on that, turning it off is not a workaround, it is trading one problem for another.

The real options today:

  • Run the CLI inside WSL instead of the Desktop app. The bug lives in the desktop app's code path, not in the CLI. The CLI inside WSL does not go through that transport.
  • Keep Desktop on native Windows and call WSL by command. Less fluid, but it preserves access to the Linux environment when you need it occasionally.
  • Do not count on a downgrade. The app updates through the Microsoft Store, which does not expose old versions, and the repo releases only ship CLI binaries. Issue #26914 asks for exactly that and still has no maintainer reply.

When does the error show up with no WSL at all?

There is a second family of causes, less common and more annoying, where WSL is off and the error persists. It usually comes from a legacy key that the renderer sends before the app finishes initializing. In that case the symptom is intermittent: it works on some launches and fails on others, and a full quit followed by a relaunch clears the session.

There is also the socket permission variant, documented in #56677 for Macs with more than one user account. The /private/tmp/codex-app-tools directory ends up owned by another account, and the app cannot create the socket. The log shows EACCES and listen EACCES: permission denied. Recovery means giving the directory access back and reopening the app, but the directory can return to the wrong state later.

SymptomCauseWhat fixes it
Every chat fails, always, on WindowsBackend inside WSL, invalid cmd.exe transportrunCodexInWindowsSubsystemForLinux = false
Intermittent failure, goes away on relaunchLegacy key sent by the renderer before initFull quit and relaunch
Fails for one Mac user only/private/tmp/codex-app-tools owned by another accountGive directory access back and reopen
Disabling the codex-app-tools pluginDoes not go through the normal toggleNothing, that route does not exist
Mirroring the block into config.tomlWorks, but paths are version specificBreaks on the next app update

What is worth learning from this error?

The failure has a trait worth recognizing in any tool: an internal component registered a transport that only exists on one operating system, and its failure is fatal for the entire session. The app does not degrade. It simply opens no conversation at all.

A broken MCP server should not take down the config load, and that is what the issue itself suggests as a third fix direction: make that server's failure non-fatal, disabling only the feature that depends on it. Until that lands, the path is to diagnose from the log and cut the cause at the root.

In Verboo Code, every MCP server is declared by you, with an explicit transport, and each one's state is visible on its own. A server that will not connect becomes one failing line, not an app that will not open. If you want to see how that works in practice, start here.

Enjoyed this article?
Share knowledge with your network.
// Read also

Related articles