Troubleshooting

no such module: vec0 / vec_version errors

You’re on Alpine/musl or hit an ABI mismatch. Use the provided node:22-bookworm-slim base (Debian/glibc) — sqlite-vec, better-sqlite3, and onnxruntime have no musl prebuilds.

Model tries to download at runtime

Confirm ALLOW_REMOTE_MODELS=0 and that the build ran dist/prefetch.js (which caches the embedding model for offline use).

A new artifact isn’t found

Call reindex (or restart) after adding a brand-new directory; otherwise the crawl is incremental by content hash.

Global Claude MCP servers seem missing

They live in ~/.claude.json — a file at $HOME, a sibling of ~/.claude/, not inside it. A scan root of just ~/.claude misses it; whole-machine roots (or SCAN_ROOTS="auto") cover it.

Project-scoped .mcp.json needs approval

Prefer claude mcp add --scope user, or run claude mcp reset-project-choices.

Drift shows executable-bit changes on Windows

NTFS has no Unix exec bit, so an upstream 100755 script can hash differently against a locally scanned copy. Compare content hashes in the drift detail — the per-file diffs are unaffected.

Remote collector push is rejected

Remote pushes require the hub bound non-loopback (HOST=0.0.0.0), which forces an auth token — pass it with --token on the collector. See Collector & hub.