Troubleshooting¶

Common install issues and how to fix them.

`command not found: uvx`¶

The plugin and the "try without installing" CLI path both need uv (which provides uvx).

See the uv install guide. After installing, open a new shell so uvx is on PATH.

Claude Code isn't installed. See the Claude Code install guide — then come back and install the plugin.

Restart Claude Code. Plugins are loaded at session start; an existing session won't pick one up.
Check uv is installed. The plugin runs uvx opentraceai mcp — without uv, the MCP server silently fails to start. See the first entry above.
Verify the plugin is listed. Run claude plugin list and make sure opentrace-oss is present.
Check plugin logs. Look in ~/.claude/logs/ for MCP startup errors.

No write permissions on .opentrace/. The database is written to .opentrace/index.db at the repo root. If the directory exists but isn't writable, indexing hangs on the first save. Fix: chmod -R u+w .opentrace/ or delete the directory and re-index.
Not in a git repo. opentraceai walks up from your current directory looking for the git root. If there isn't one, it falls back to the current directory — make sure that's what you want.

OpenTrace needs Cross-Origin Isolation, which means:

Chrome / Edge 91+, Firefox 119+.
Safari does not currently work — see Browser Requirements.
Link-preview embedded browsers (Slack, Discord, iMessage) don't support it either. Open the URL in a real browser tab.

cd ui
PORT=5174 npm run dev

See Configuration for details.

Node version. OpenTrace needs Node.js 22+. Check with node --version; see ui/.nvmrc.
Python version. The agent needs Python 3.12+. Check with python --version.
Missing uv. The agent install uses uv sync. Install uv as above.

Install paths: Browser · CLI · Plugin · Source