Guides

Troubleshooting

Common issues and their solutions when working with vibe-hnindex.

Windows npm Install

The most common issue on Windows is failing to install because of native dependencies.

Symptoms

npm i vibe-hnindex fails
Log mentions better-sqlite3, prebuild-install, node-gyp
Error about No prebuilt binaries found
Reference to Visual Studio or Desktop development with C++

Why

better-sqlite3 contains native code. npm either downloads a prebuilt binary or compiles with node-gyp. On some Node + Windows combinations, there is no prebuild, so npm tries to compile — which requires Visual Studio Build Tools.

Solutions (pick one)

1. Use LTS Node

Use Node.js 20.x or 22.x LTS. Many LTS versions have prebuiltbetter-sqlite3. No compiler needed.

2. Install Build Tools

Install Visual Studio Build Tools with workload "Desktop development with C++".

3. Avoid Bleeding Edge

Avoid very new Node versions on Windows — prebuilds often lag behind.

Deprecation warnings (fs.R_OK, url.parse) are noisy but usually not the root cause. The real failure is node-gyp / missing VS or no prebuild.

Runtime Error Handling

Situation	Behavior
Ollama unavailable	Error message; keyword search still works
Qdrant unavailable	Error message; keyword search still works
Hybrid with services down	Falls back to keyword + warning
Unreadable/huge/binary file	Skipped; reported in index summary

Qdrant Cloud Issues

401 / Auth Errors

Set QDRANT_API_KEY to the key from your Qdrant Cloud dashboard
Ensure QDRANT_URL is the exact HTTPS endpoint with port (:6333)

Connection Timeout

Increase QDRANT_TIMEOUT_MS (default 15s) for remote clusters

Ollama Issues

Model Not Found

ollama pull bge-m3:567m

Verify the model is pulled and ollama serve is running.

Switching Embedding Models

Changing OLLAMA_MODEL requires updating EMBEDDING_DIMENSIONS and re-indexing:

Pull the new model: ollama pull nomic-embed-text
Update MCP env: OLLAMA_MODEL=nomic-embed-text, EMBEDDING_DIMENSIONS=768
Delete existing project: delete_project(project_name: "my-app")
Re-index: index_codebase(path: "/path", project_name: "my-app")
Verify: server_diagnostics()

The Qdrant collection is created with a fixed vector size. Changing the embedding model without deleting + re-indexing will cause dimension mismatch errors.

Dimension Mismatch

If you see errors like "dimension mismatch" or "wrong vector size", it meansEMBEDDING_DIMENSIONSdoesn't match the model's actual output. Delete the Qdrant collection and re-create it with the correct dimensions.

Model	Correct Dimension
`bge-m3:567m`	`1024`
`nomic-embed-text`	`768`
`mxbai-embed-large`	`1024`
`all-minilm`	`384`
`snowflake-arctic-embed2`	`1024`
`qwen3-embedding`	`32-4096` (configurable)

Remote Ollama

Set OLLAMA_URL=http://your-server:11434 in MCP env. Increase OLLAMA_TIMEOUT_MS for remote servers.

FAQ

Where is data stored?

SQLite: ~/.vibe-hnindex/knowledge.db (or STORAGE_PATH). Qdrant: your Docker volume or Cloud project.

Does a new chat lose the index?

No. Data is on disk until you run delete_project.

Is Docker required?

Only for self-hosted Qdrant. Keyword mode works without Qdrant or Ollama.

Can Ollama run on another machine?

Yes — set OLLAMA_URL in MCP env.

Is re-indexing slow?

No. Incremental indexing only reprocesses files with changed SHA-1 hashes.

Can I use vibe-hnindex without Ollama?

Yes — keyword search (FTS5) works without Ollama. Only semantic/hybrid need embeddings.

Can I use vibe-hnindex without Docker?

Yes — keyword search works without Qdrant. Use Qdrant Cloud if you don't want Docker.

Running Diagnostics

Use the server_diagnostics tool for a health check:

server_diagnostics()
server_diagnostics(project_name: "my-app")

This checks:

Ollama reachability
Embedding probe (optional: embedSingle("ping"))
Qdrant reachability
Config summary
Project-specific: SQLite vs Qdrant chunk count comparison

PreviousPerformance