Tools return "not available"

Your client says MCP tools are not available or cannot find trw_* functions. Cause: The generated MCP config is missing, misconfigured, or trw-mcp is not on PATH. Fix: Verify the generated client config exists with a TRW entry (.mcp.json, .cursor/mcp.json, .codex/config.toml, or .gemini/settings.json). Check PATH: which trw-mcp Reinstall: pip install trw-mcp Restart the client after install so it reloads its MCP configuration.

Server won't start / [Errno 2] errors

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. Fix: Use the client-specific reconnect or restart action first (for example /mcp where supported). If that fails, start manually: make mcp-server Check logs: cat .trw/logs/mcp-server.log Verify status: make mcp-server-status

Server dies after code changes

MCP tools stop working after editing files in trw-mcp/src/. Cause: The MCP server loads code at startup. Changes require a restart. Fix: Restart or reconnect the current client so it launches a fresh MCP process. If the shared server stays unhealthy, run make mcp-server-stop then make mcp-server.

WSL2 cold start timeout

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. Fix: Wait 30 seconds after boot, then retry. Pre-warm by running any command in WSL2 terminal first. Start explicitly: make mcp-server

pip install fails with dependency conflicts

pip install trw-mcp fails with dependency resolver errors. Cause: Conflicting package versions, often from pydantic, fastmcp, or anthropic SDK. Fix: Use a virtual environment: python -m venv .venv && source .venv/bin/activate Install fresh: pip install trw-mcp Check versions: pip freeze | grep -E "pydantic|fastmcp"

Bootstrap fails — missing .trw directory

trw-mcp init-project . fails or .trw/ is not created. Cause: Permission issues or running outside your project root. Fix: Ensure you are in your project root: pwd Check permissions: touch .trw-test && rm .trw-test Run init: trw-mcp init-project . Verify: ls -la .trw/

Config not found after init

Tools report "config not found" after running init-project. Cause: Tool is looking in the wrong directory or env vars override the path. Fix: Verify: cat .trw/config.yaml Check for TRW_CONFIG_PATH environment variable. Re-run: trw-mcp init-project . to regenerate.

trw_session_start returns no learnings

trw_session_start() reports zero learnings loaded. Cause: Normal for new projects. Learnings accumulate over sessions. Fix: No action needed -- this is expected for new projects. After a few sessions with trw_learn() calls, recall returns entries. Test storage: trw_learn(summary="test"), then trw_recall("test").

trw_build_check path not found

trw_build_check() errors with "path not found" or "no tests discovered". Cause: Missing project paths in .trw/config.yaml. Fix: Set source_package_path in .trw/config.yaml Set source_package_name for coverage tracking. Set tests_relative_path to your test directory.

CeremonyMiddleware warnings

Every tool response is prepended with a ceremony warning. Cause: Middleware enforces trw_session_start() is called first. Fix: Call trw_session_start() at the beginning of your session.

Session interrupted — recovering work

The client session ended unexpectedly. Cause: Rate limits, network issues, or context window compaction. Fix: Start a new session. Call trw_session_start() -- it detects the active run. Call trw_status() to see your last checkpoint. Continue from where you left off.

Session-start or other automation surfaces do not execute. Cause: Missing registrations, non-executable scripts, or a profile that intentionally uses lighter automation. Fix: Check the selected client surface (.claude/settings.json, .cursor/hooks.json, .github/hooks/hooks.json, etc.). Make shell hooks executable when the profile uses shell scripts: chmod +x .claude/hooks/*.sh or chmod +x .cursor/hooks/*.sh If you selected a light profile such as OpenCode, Codex, or Aider, verify the behavior is expected — those profiles rely more on instructions than shell hooks.

Amplify build failures

Push to main triggers a build that fails, though local build passes. Cause: Amplify clones fresh from git. Uncommitted files cause MODULE_NOT_FOUND. Fix: Commit all new files: git status Verify package.json changes are committed. Check: make amplify-status Test locally: rm -rf node_modules && npm ci && npm run build

Port conflicts (3000, 8000, 5432)

Docker containers fail with "port already in use". Cause: Other services using required ports. Fix: Check usage: lsof -i :3000 Stop conflicting services or change ports in docker-compose.yml.

SQLite lock contention

"database is locked" errors during concurrent operations. Cause: Multiple processes writing to the same SQLite database. Fix: Ensure one MCP server: make mcp-server-status Stop the shared server cleanly: make mcp-server-stop Restart cleanly: make mcp-server

Pydantic validation errors

ValidationError from Pydantic v2 when calling tools or loading config. Cause: Data shape mismatch from config edits or API changes. Fix: Read the error -- it shows which field failed. Check .trw/config.yaml against the model in models/config.py. Re-run trw-mcp init-project . for a valid default.

Docs

Troubleshooting

Solutions for common issues when working with TRW. For initial setup, see the Quickstart.

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

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 and setup

Runtime errors

Docker and 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.

Quickstart

Installation and first session walkthrough

Configuration

All config options and environment variables

API reference

Hosted platform auth, telemetry, and admin endpoints

Start with the fastest checks

Then match the failure to a category

MCP server issues

Tools return "not available"Your client says MCP tools are not available or cannot find trw_* functions.

Server won't start / [Errno 2] errorsTool calls fail with [Errno 2] No such file or directory or "MCP server not reachable".

Server dies after code changesMCP tools stop working after editing files in trw-mcp/src/.

WSL2 cold start timeoutFirst MCP call after boot takes 15-20s and may time out.

Installation and setup

pip install fails with dependency conflictspip install trw-mcp fails with dependency resolver errors.

Bootstrap fails — missing .trw directorytrw-mcp init-project . fails or .trw/ is not created.

Config not found after initTools report "config not found" after running init-project.

Runtime errors

trw_session_start returns no learningstrw_session_start() reports zero learnings loaded.

trw_build_check path not foundtrw_build_check() errors with "path not found" or "no tests discovered".

CeremonyMiddleware warningsEvery tool response is prepended with a ceremony warning.

Session interrupted — recovering workThe client session ended unexpectedly.

Hooks not firingSession-start or other automation surfaces do not execute.

Docker and deployment

Amplify build failuresPush to main triggers a build that fails, though local build passes.

Port conflicts (3000, 8000, 5432)Docker containers fail with "port already in use".

SQLite lock contention"database is locked" errors during concurrent operations.

Pydantic validation errorsValidationError from Pydantic v2 when calling tools or loading config.

WSL2 file system notes

Where to go next

Once the broken path is fixed, harden the day-two setup.