Troubleshooting
No graph found
Symptom: export or mcp-start reports no graph or missing .genome/watcher.db.
Fix: Run codegenome analyze . in the workspace first.
unrecognized arguments
Symptom: CLI error when mixing flags and subcommands.
Fix: Use only one style:
- Modern:
codegenome analyze . - Legacy:
python -m codegenome --workspace . --build
See Legacy flag CLI.
codegenome: command not found
- Activate your virtual environment
- Or run
python -m codegenome.cli analyze . - Verify install:
pip show codegenome
igraph / leidenalg build failure
Install platform build tools (see Installation), then retry pip install codegenome.
MCP connection refused
- Ensure MCP process is running (
--mcpormcp_server) - Graph was built:
codegenome analyze . - Check health:
curl http://127.0.0.1:7331/health
Port 7331 in use
Stop the other instance or use a custom port:
python -m codegenome.mcp_server --db-path ./.genome/watcher.db --port 7332
Update installer and rules with the same port.
Empty MCP tool results
- Rebuild graph after large code changes
- Confirm
--db-pathpoints to the correct workspace DB - Restart the AI client after running
installer
Empty timeline dumps
Run at least one successful --build before --dump-timeline.