Troubleshooting

Start with three checks:

zg version
zg status
zg help

The zg Command Is Unavailable

Zvec-Grep requires Node.js 22 or newer:

node --version
npm install -g @zvec/zvec-grep
zg version

If npm succeeds but zg is still missing, add npm's global binary directory to your shell PATH.

The Index Is Missing or Stale

Run commands from the intended workspace root:

zg status --check-ready
zg index
zg query "release checklist" --refresh wait

Use --rebuild only when changing the embedding model or intentionally replacing stored index settings.

Search Results Are Empty or Weak

1. Use --rg for known text, identifiers, paths, or regex.
2. Use --fts for known terms that need ranking.
3. Use the default hybrid query when wording or location is unknown.
4. Restrict broad workspaces with -g, -t, or -T.
5. Confirm that the content is indexed and the model fits it.

zg query "authentication flow" --debug --trace
zg index --debug

See Search Guide, Supported Content, and Embedding Models.

Explicit Server Mode Is Not Ready

This applies only when using --mode server or an HTTP MCP connection. Default stdio Agent integrations manage the service automatically.

zg server status --check-ready
zg server on
zg server status --check-ready

Run zg server run when you need foreground logs. See Local Server for lifecycle, client mode, listen address, and authentication.

An Agent Cannot Use Zvec-Grep

zg install --target codex --yes

Restart the Agent or open a new session. Exact identifiers and filenames may correctly use its native grep instead of Zvec-Grep. See Connect AI Agents.

Remote Embedding Is Denied

Inspect or grant the separate workspace authorization:

zg auth status
zg auth grant --capability embedding --scope workspace --embedding qwen/text-embedding-v4

Use --allow-remote for one command, or choose a local model when content must not leave the machine.

Reset Safely

zg index --rebuild --embedding local/potion-code-16m-v2
zg index --drop --yes

When reporting a problem, include the version, operating system, failing command, relevant zg status, and sanitized diagnostics. Remove credentials, private paths, and sensitive excerpts.

Open a Zvec-Grep issue