Codex app-server: initialize handshake timed out

A session that hangs on "Timed out waiting for initialize" is almost always an outdated Codex CLI failing the app-server handshake. The fix, and why it happens.

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

You start a session, it sits there, and eventually:

Timed out waiting for initialize

The initialize handshake between your client and codex app-server never completed. Clients word this differently — you may see it as a plain timeout, as "initialize handshake timed out", or as a session that simply never starts — but it is one failure with one usual cause.

The fix#

Update your Codex CLI. That's it, in the overwhelming majority of cases.

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

Then fully restart T3 Code — quit the app or kill the npx t3 process, don't just refresh the browser. The old subprocess needs to go away.

This is a documented case: an outdated Codex CLI at version 0.42.0 caused exactly this failure, and updating to a current release resolved it.

Why it happens#

T3 Code launches codex app-server and speaks JSON-RPC over stdio to it. Startup begins with an initialize handshake.

Two independently-versioned tools sit either side of that handshake. T3 Code ships nightly builds; Codex updates on OpenAI's schedule. When the protocol moves and one side hasn't caught up, the initialize never completes — and instead of a clear "your CLI is too old" message, you get a timeout, because a timeout is all the calling side can observe.

There's an open feature request to add explicit Codex version compatibility checks so this surfaces as a real message. Until that lands, updating is the fix.

Architecture in detail →

If updating didn't fix it#

Work through these in order.

1. Confirm which binary is actually running#

You may have two Codex installs and be updating the wrong one:

which codex          # macOS / Linux
where codex          # Windows
codex --version

If which codex points somewhere you don't recognise — an old nvm version directory, a stale Homebrew path — remove it or fix your PATH.

2. Check the CLI works standalone#

codex login
codex

If Codex alone can't start a session, this was never a T3 Code problem.

3. Look for a stale subprocess#

A previous crashed session can leave a codex process holding things up:

# macOS / Linux
ps aux | grep codex
kill -9 <pid>

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

4. Check port 9234#

Codex uses 127.0.0.1:9234 for remote connections, and a conflict there blocks app-server bootstrap in a way that can present as a startup hang:

lsof -ti:9234                     # macOS / Linux
netstat -ano | findstr :9234      # Windows

More on port conflicts →

5. Re-authenticate#

codex login

An expired session can stall the handshake rather than failing cleanly.

6. Update T3 Code too#

If your Codex is current, the skew may be the other way:

npx t3@latest

Preventing it#

• Update both together. When you update T3 Code, update the provider CLI in the same sitting.
• Or pin both. For team setups, pin a known-good T3 Code version and a known-good Codex version. Version guidance →
• Check versions first when reporting bugs. It's the first question you'll be asked.

FAQ#

What causes "Timed out waiting for initialize" in T3 Code?#

An outdated provider CLI whose app-server protocol no longer matches what T3 Code expects. The initialize handshake never completes, so the calling side times out.

How do I fix the T3 Code initialize timeout?#

Run npm i -g @openai/codex@latest, verify with codex --version, then fully restart T3 Code rather than just refreshing the browser.

Why doesn't T3 Code say my CLI is too old?#

Because it can only observe that initialize never completed, not why. There's an open request to add explicit version compatibility checks that would report this clearly.

Do I need to restart T3 Code after updating Codex?#

Yes, fully. Quit the app or kill the npx t3 process so the stale provider subprocess is replaced. Refreshing the browser is not enough.