Troubleshooting
CARI Issues
Section titled “CARI Issues”“No index found” / Empty results
Section titled ““No index found” / Empty results”iw index retrieve "something"# Error: No index found at .iw/index.dbFix: Run iw init then iw index build first.
Index is empty (0 annotations)
Section titled “Index is empty (0 annotations)”If iw index build completes but queries return nothing:
- Check your project has source files (
.ts,.js,.swift,.py) and Markdown docs - Run with verbose:
iw index build -vto see stage output - Verify tree-sitter can parse your files (currently supports TS/JS/Swift/Python)
“tree-sitter build failed”
Section titled ““tree-sitter build failed””tree-sitter requires a C compiler for native bindings.
macOS:
xcode-select --installUbuntu/Debian:
sudo apt-get install build-essentialAlpine (Docker):
apk add python3 make g++Slow build times
Section titled “Slow build times”For most projects, iw index build takes 1–3 seconds. If it’s slow:
- Check file count: CARI indexes all files in the workspace
- Use
--includeto limit scope:iw index build --include "src/**" --include "docs/**" - Use
--excludeto skip large directories:iw index build --exclude "node_modules/**"
MCP Issues
Section titled “MCP Issues”Copilot doesn’t see IntentWeave tools
Section titled “Copilot doesn’t see IntentWeave tools”-
Verify
.vscode/mcp.jsonexists:{"servers": {"intentweave-kg": {"command": "npx","args": ["@intentweave/cli", "mcp", "--session", "my-project", "-v"]}}} -
Restart VS Code after adding the config
-
Check the MCP server starts manually:
Terminal window iw mcp --session my-project -v
MCP tools return errors
Section titled “MCP tools return errors”- CARI tools (
cari_retrieve, etc.): Runiw index buildfirst - KG tools (
kg_query, etc.): install the graph plugin withiw plugin add kg-lite
General Issues
Section titled “General Issues”“iw: command not found”
Section titled ““iw: command not found””Install globally:
npm install -g @intentweave/cliOr use npx:
npx @intentweave/cli <command>Node.js version
Section titled “Node.js version”IntentWeave requires Node.js ≥ 22.15 (for the built-in node:sqlite module):
node -v# Should show v22.15.0 or higherCache issues
Section titled “Cache issues”If results seem stale:
# Rebuild from scratchiw index build --force