Troubleshooting

Most Altor Vec issues fall into a small number of categories: the WebAssembly asset does not load, vectors have the wrong dimension, index build settings are too aggressive for the available memory, or search quality is poor because the embedding pipeline is inconsistent. The best debugging approach is to isolate these possibilities one by one instead of changing multiple variables at the same time.

Start with the environment. Confirm that the package version in your application matches the artifact you expect, and verify that the Wasm file is actually being served in browser builds. If initialization fails before any records are added, the problem is usually packaging or runtime support rather than the search engine itself.

Common Errors

A dimension mismatch error means the engine was created with one size and later received a vector of another size. This can happen when embeddings are generated by different models, when vectors are truncated incorrectly, or when serialized indexes are loaded into an engine configured for a different dimension.

If search returns empty or obviously irrelevant results, inspect the actual numbers before blaming HNSW. Zero vectors, NaN values, or partially normalized embeddings will corrupt relevance quickly. Likewise, duplicated content chunks can crowd the result set with near-identical matches.

if (queryVector.length !== 384) {
  throw new Error(`Expected 384 dimensions, received ${queryVector.length}`);
}

Debugging Workflow

Use a small fixture index first. Insert five to ten records with known semantic relationships, then run a query you can evaluate by hand. If that behaves correctly, scale up gradually while logging record count, memory usage, and query latency. Raise ef_search before changing m unless you are rebuilding the full index anyway.

For browser issues, open the network panel and confirm the Wasm asset resolves successfully. For Node.js issues, log the library version, platform, and engine options at startup. Clear reproduction details matter because many search bugs are really data-pipeline bugs. The closer your debugging fixture is to production data shape, the faster you will find the true cause.