T3 Code troubleshooting
The errors people actually hit with T3 Code — startup timeouts, missing provider binaries, port conflicts and remote session failures — each with a working fix.
Before anything else, try these three. They resolve the majority of reported problems.
# 1. update your provider CLI — the single highest-yield fix
npm i -g @openai/codex@latest
codex --version
# 2. confirm the provider works on its own
codex login
# 3. make sure nothing else holds the port
lsof -ti:3773 # macOS / Linux
netstat -ano | findstr :3773 # WindowsIf you're still stuck, find your symptom below.
Error index#
| Symptom | Cause | Fix |
|---|---|---|
Timed out waiting for initialize | Outdated provider CLI | Fix → |
'codex' not found but it works in your shell | PATH not inherited | Fix → |
EADDRINUSE / server won't start | Port 3773 or 9234 taken | Fix → |
failed to start codex app-server | Spawn or path failure, often Windows | Fix → |
manifest entry is missing required path | Stale native-messaging manifest after an update | Fix → |
Codex process is not available | App-server launched, then crashed | Fix → |
Couldn't set up admin/non-admin sandbox | Windows sandbox ACL failure | Fix → |
exceeded retry limit, last status: 429 | Quota, auth or provider — read the status code | Fix → |
| Provider update loops forever | npm permissions or stale lock | Fix → |
Missing key at ["thread"]["sessionId"] | Remote adapter mismatch | Fix → |
| Can't add a project on a remote server | Known GUI limitation | Use t3 project on the server — details |
Diagnose by layer#
Almost every failure belongs to one layer, and knowing which one narrows the fix immediately:
Browser ──ws──► Node server ──JSON-RPC──► Provider CLI ──https──► Model
1 2 3 4| What you see | Layer | Meaning |
|---|---|---|
| Page loads, spinner forever | 1→2 | Server not reachable, or WebSocket blocked |
| Server won't start at all | 2 | Port conflict |
| Server fine, session won't start | 2→3 | Provider CLI missing, old, or unauthenticated |
| Session starts then dies mid-run | 3→4 | Auth expired, rate limit, quota |
| Rate limit / billing messages | 4 | Your provider account, not T3 Code |
Codex errors that aren't T3 Code errors#
A large share of what people bring here originates in the Codex CLI, not in T3 Code — T3 Code just launches it as a subprocess, so Codex's failures surface inside T3 Code's UI.
These are worth separating out, because the fix always belongs at the Codex layer and several of them are open upstream bugs with no official fix yet:
| Error | What it means |
|---|---|
failed to start codex app-server | Never launched — path resolution, or Microsoft Store ACLs |
manifest entry is missing required path | Stale native-messaging manifest left behind by a plugin update |
Codex process is not available | Launched, then crashed — usually an unknown feature key |
Couldn't set up the sandbox | Windows ACL/ownership failure — one variant corrupts your repo |
exceeded retry limit, last status: 429 | The status code is the real error; 429, 401 and 503 differ |
The diagnostic that settles it: run a plain codex session in a terminal. If that fails too, it was never a T3 Code problem.
Things that aren't bugs#
- The GUI can't add projects on a remote server. Documented limitation. Use
t3 projecton the server machine. - Breaking changes between nightlies. The project is explicitly very early stage and ships most days. Pin a version if you need stability.
- Agent quality complaints. How good the code is comes from Codex or Claude, not from T3 Code. T3 Code is the interface.
- Rate limits. Your provider account. Agentic runs consume far more tokens than chat.
Escalating#
If none of this helps:
- Search existing issues — this project moves fast and your problem is often already fixed on a newer build
- Ask in Discord, where breakage surfaces first
- Open an issue with your T3 Code version, provider CLI version, OS, and the terminal output — without those four, the answer will just be "update your CLI"
FAQ#
Why is T3 Code not working?#
The most common causes are an outdated provider CLI, a provider binary that isn't on the PATH T3 Code inherited, or another process holding port 3773. Update the CLI first — it resolves the largest share of reported problems.
Where are T3 Code's error logs?#
The most useful output goes to the terminal where you launched npx t3. Subprocess spawn failures appear there, while the browser typically shows only a generic connection error.
Is T3 Code stable enough to rely on?#
It's usable for daily development, but the project describes itself as very early stage with expected bugs and breaking changes, and ships nightly builds. Pin a version if you need reproducibility.
Should I report a T3 Code bug or a provider bug?#
Check whether the provider CLI works on its own first. If codex --version or a plain codex session fails, it's a provider problem. If the CLI works standalone but fails through T3 Code, report it to T3 Code with both version numbers.