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 → |
| 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 |
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.