Troubleshooting

Start with three checks:

zg --version
zg --status
zg --help

The zg Command Is Unavailable

The npm installer requires Node.js 14.14 or newer; zg itself runs as a native executable:

node --version
npm install -g @zvec/zvec-grep --allow-scripts=@zvec/zvec-grep
zg --version

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

If npm skipped the package's installation scripts, enable them and run npm rebuild -g @zvec/zvec-grep --allow-scripts=@zvec/zvec-grep --foreground-scripts to materialize the native executable.

The Index Is Missing or Stale

Run commands from the intended workspace root:

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

Use --rebuild when changing the embedding model or when status reports an incompatible index. For an incompatible index, specify the desired model and scan rules again; existing data is not migrated in place.

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 "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

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