Troubleshooting

Troubleshooting

omnicode not on PATH

export PATH="$(npm config get prefix)/bin:$PATH"

Add to ~/.bashrc or ~/.zshrc to persist.

Missing required tool

[omnicode] ERROR: missing required tool(s): opencode, omniroute

npm install -g opencode
npm install -g omniroute

OmniRoute does not start

Check the log:

cat ~/.local/share/omnicode/omniroute.log

Verify omniroute --no-open works directly. For Node version mismatches:

omniroute runtime repair

Qdrant container fails to start

Requires Docker. Verify Docker is installed and running:

docker info

Manually start the container:

docker run -d --name omnicode-qdrant -p 6333:6333 -v ~/.local/share/omnicode/qdrant-storage:/qdrant/storage qdrant/qdrant

Check container logs:

docker logs omnicode-qdrant

Duplicate MCP servers

If omnicode status shows qdrant running but qdrant-find tools fail with fast-all-minilm-l6-v2 errors, stale MCP server processes may be using an old model. Kill them:

pkill -f "mcp-server-qdrant"

OpenCode will respawn a fresh MCP server with the correct environment.

Qdrant tool calls fail with vector name mismatch

Error: Not existing vector name error: fast-all-minilm-l6-v2

The collection was created with a different embedding model. Re-index with the current model:

omnicode index --force-reindex

System freeze during indexing

If the computer becomes unresponsive during omnicode index, indexing now supports Ctrl+C to cancel safely. The MCP server is stopped and partial state is saved. On next run, only unindexed files are processed.

GrayMatter or OpenSpec init fails

Non-fatal. Check captured logs:

cat ~/.local/share/omnicode/graymatter-init.log
cat ~/.local/share/omnicode/openspec-init.log

Check runtime status

omnicode --status

Shows OpenCode, OmniRoute, Qdrant, and active indexers.

Clean uninstall

sudo npm uninstall -g @meyverick/omnicode
rm -rf ~/.local/share/omnicode
docker rm -f omnicode-qdrant 2>/dev/null