Troubleshooting
Solutions for common issues when working with TRW. For initial setup, see the Quickstart.
Quick Answers
The three most common issues and their one-line fixes.
| 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.
MCP Server Issues
Tools return "not available"
Symptom: Claude Code says MCP tools are not available or cannot find trw_* functions.
Cause: .mcp.json is missing, misconfigured, or trw-mcp is not on PATH.
- 1Verify .mcp.json exists with a "trw" entry.
- 2Check PATH: which trw-mcp
- 3Reinstall: pip install trw-mcp
- 4Restart: type /mcp in Claude Code.
Server won't start / [Errno 2] errors
Symptom: Tool calls fail with [Errno 2] No such file or directory or "MCP server not reachable".
Cause: The MCP server process has died or was never started. Common after system sleep, WSL2 restarts, or unhandled exceptions.
- 1Type /mcp in Claude Code to reconnect (auto-starts the server).
- 2If that fails, start manually: make mcp-server
- 3Check logs: cat .trw/logs/mcp-server.log
- 4Verify status: make mcp-server-status
Server dies after code changes
Symptom: MCP tools stop working after editing files in trw-mcp/src/.
Cause: The MCP server loads code at startup. Changes require a restart.
- 1Type /mcp in Claude Code to restart.
- 2For development, use make mcp-server with --debug for verbose logging.
WSL2 cold start timeout
Symptom: First MCP call after boot takes 15-20s and may time out.
Cause: WSL2 needs time to initialize. The auto-start proxy has a 30s timeout.
- 1Wait 30 seconds after boot, then retry.
- 2Pre-warm by running any command in WSL2 terminal first.
- 3Start explicitly: make mcp-server
Installation & Setup
pip install fails with dependency conflicts
Symptom: pip install trw-mcp fails with dependency resolver errors.
Cause: Conflicting package versions, often from pydantic, fastmcp, or anthropic SDK.
- 1Use a virtual environment: python -m venv .venv && source .venv/bin/activate
- 2Install fresh: pip install trw-mcp
- 3Check versions: pip freeze | grep -E "pydantic|fastmcp"
Bootstrap fails -- missing .trw directory
Symptom: trw-mcp init-project . fails or .trw/ is not created.
Cause: Permission issues or running outside your project root.
- 1Ensure you are in your project root: pwd
- 2Check permissions: touch .trw-test && rm .trw-test
- 3Run init: trw-mcp init-project .
- 4Verify: ls -la .trw/
Config not found after init
Symptom: Tools report "config not found" after running init-project.
Cause: Tool is looking in the wrong directory or env vars override the path.
- 1Verify: cat .trw/config.yaml
- 2Check for TRW_CONFIG_PATH environment variable.
- 3Re-run: trw-mcp init-project . to regenerate.
Runtime Errors
trw_session_start returns no learnings
Symptom: trw_session_start() reports zero learnings loaded.
Cause: Normal for new projects. Learnings accumulate over sessions.
- 1No action needed -- this is expected for new projects.
- 2After a few sessions with trw_learn() calls, recall returns entries.
- 3Test storage: trw_learn(summary="test"), then trw_recall("test").
trw_build_check path not found
Symptom: trw_build_check() errors with "path not found" or "no tests discovered".
Cause: Missing project paths in .trw/config.yaml.
- 1Set source_package_path in .trw/config.yaml
- 2Set source_package_name for coverage tracking.
- 3Set tests_relative_path to your test directory.
CeremonyMiddleware warnings
Symptom: Every tool response is prepended with a ceremony warning.
Cause: Middleware enforces trw_session_start() is called first.
- 1Call trw_session_start() at the beginning of your session.
Session interrupted -- recovering work
Symptom: Claude Code session ended unexpectedly.
Cause: Rate limits, network issues, or context window compaction.
- 1Start a new session.
- 2Call trw_session_start() -- it detects the active run.
- 3Call trw_status() to see your last checkpoint.
- 4Continue from where you left off.
Hooks not firing
Symptom: Session-start or other Claude Code hooks do not execute.
Cause: Missing registrations or non-executable scripts.
- 1Check .claude/settings.json for hook registrations.
- 2Make executable: chmod +x .claude/hooks/*.sh
- 3Verify: cat .claude/hooks/session-start.sh
Docker & Deployment
Amplify build failures
Symptom: Push to main triggers a build that fails, though local build passes.
Cause: Amplify clones fresh from git. Uncommitted files cause MODULE_NOT_FOUND.
- 1Commit all new files: git status
- 2Verify package.json changes are committed.
- 3Check: make amplify-status
- 4Test locally: rm -rf node_modules && npm ci && npm run build
Port conflicts (3000, 8000, 5432)
Symptom: Docker containers fail with "port already in use".
Cause: Other services using required ports.
- 1Check usage: lsof -i :3000
- 2Stop conflicting services or change ports in docker-compose.yml.
SQLite lock contention
Symptom: "database is locked" errors during concurrent operations.
Cause: Multiple processes writing to the same SQLite database.
- 1Ensure one MCP server: make mcp-server-status
- 2Kill stale: pkill -f trw-mcp
- 3Restart: make mcp-server
Pydantic validation errors
Symptom: ValidationError from Pydantic v2 when calling tools or loading config.
Cause: Data shape mismatch from config edits or API changes.
- 1Read the error -- it shows which field failed.
- 2Check .trw/config.yaml against the model in models/config.py.
- 3Re-run trw-mcp init-project . for a valid default.
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).