Docs
Troubleshooting
Solutions for common issues when working with TRW. For initial setup, see the Quickstart.
Client-aware debugging
Modern installs can target several clients in one repo. When debugging, inspect the surface you actually selected during install — not just one familiar default path.
Start with the fastest checks
Check these first. They resolve the most common onboarding and day-to-day failures in a few seconds.
| Issue | Fix |
|---|---|
| Tools “not available” | Check .mcp.json exists, then type /mcp in Claude Code |
| [Errno 2] server errors | Type /mcp to reconnect (auto-restarts the server) |
| Ceremony warnings on every call | Call trw_session_start() first -- middleware requires it |
Tip
Can't find your issue? Try trw_recall('your error message') — prior agents may have already documented a fix in your project's learnings.
Then match the failure to a category
If the quick checks do not fix it, use the category below that matches where the failure occurs: MCP connection, local setup, runtime behavior, or deployment.
MCP Server Issues
Installation & Setup
Runtime Errors
Docker & Deployment
WSL2 File System Notes
- Intermittent ENOENT errors are transient -- retry usually resolves them immediately.
- For persistent issues, work in the Linux filesystem (~/) instead of /mnt/c/.
- Set WATCHPACK_POLLING=true for Next.js hot-reload (already set in dev compose).
Where to go next
If this is an install or access problem, go back to quickstart. If the issue is configuration-, auth-, or environment-specific, continue into configuration or the hosted API reference.