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 .antigravitycli/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) — every client spawns its own trw-mcp over stdio, so reconnecting relaunches it. Confirm the binary still resolves: which trw-mcp Check logs under .trw/logs/ for the most recent server entries.

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 (for example /mcp) so it launches a fresh MCP process. Each session spawns its own trw-mcp over stdio, so reconnecting always picks up the new code.

WSL2 cold start timeout

First MCP call after boot takes 15-20s and may time out. Cause: WSL2 needs time to initialize before the client can spawn trw-mcp over stdio. Fix: Wait ~30 seconds after boot, then retry the first tool call. Pre-warm by running any command in the WSL2 terminal first. Reconnect the client (for example /mcp where supported) to relaunch the 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.

Installing behind a proxy or on an air-gapped host

Install fails because the host cannot reach PyPI directly, or sits behind a corporate proxy / TLS-inspecting gateway. Cause: No direct outbound network, or a proxy and custom CA bundle are required. Fix: Proxy: export HTTPS_PROXY / HTTP_PROXY / NO_PROXY before running the installer. Custom CA: export SSL_CERT_FILE=/path/to/ca-bundle.pem (and REQUESTS_CA_BUNDLE) so TLS validates. Offline: run the installer with --offline — it installs trw-mcp + trw-memory from the embedded wheels via --no-index and never reaches PyPI. Pass the API key via the TRW_API_KEY environment variable (keeps it out of the process argv).

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 records the wrong result

The delivery gate shows missing or inaccurate validation evidence. Cause: trw_build_check records evidence supplied by the caller. It does not discover paths, run tests, or infer a command result. Fix: Run the project-native test, build, lint, or type-check command first. Pass tests_passed, test_count, failure_count, scope, and static_checks_clean explicitly. Only pass coverage_pct when the command actually measured coverage.

CeremonyMiddleware warnings

Every tool response is prepended with a ceremony warning. Cause: Middleware warns when trw_session_start() has not been 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 Check the selected profile guide before assuming every client exposes the same hook events; hooks are optional adapters, not a correctness boundary.

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 trw-mcp processes writing to the same SQLite database concurrently. Fix: Reduce concurrent clients pointed at the same .trw/ directory — each client spawns its own trw-mcp over stdio against the shared database. Reconnect a wedged client (for example /mcp) to release a stale lock; WAL mode retries most contention automatically. Confirm no leftover trw-mcp process is holding the DB: pgrep -fa trw-mcp

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 models under trw_mcp/models/config/. 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.

01Check
Confirm the selected client surface
Check that the generated MCP config for the client you selected still contains its TRW entry.
02Check
Confirm the executable
Run which trw-mcp from the same environment that launches your client, then restart or reconnect that client.
03Check
Start with project context
Call trw_session_start() before other TRW tools so middleware can load learnings and recover an active run.

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 local storage

WSL2 file system notes

Retry an intermittent ENOENT once; if it repeats, confirm the executable and generated client path instead of treating it as transient.
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

Confirm the selected client surface

Confirm the executable

Start with project context

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.

Installing behind a proxy or on an air-gapped hostInstall fails because the host cannot reach PyPI directly, or sits behind a corporate proxy / TLS-inspecting gateway.

Runtime errors

trw_session_start returns no learningstrw_session_start() reports zero learnings loaded.

trw_build_check records the wrong resultThe delivery gate shows missing or inaccurate validation evidence.

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 local storage

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.