Atlas: diagnose slow or bad $vectorSearch results

TL;DR: Vector search is slow or returns junk. The causes are almost always index config: dimensions, candidates, readiness, or filter fields. Too low and recall collapses (good docs never surface); way too high and latency balloons. Confirm Run the same query with numCandidates raised 10x.

The fix

TL;DR: Vector search is slow or returns junk. The causes are almost always index config: dimensions, candidates, readiness, or filter fields. Too low and recall collapses (good docs never surface); way too high and latency balloons. Confirm Run the same query with numCandidates raised 10x.

The error

`$vectorSearch` is slow, returns irrelevant results, or errors.

The fix

1. getSearchIndexes(): is the index READY? BUILDING explains errors and empty results.
2. numDimensions in the index vs your embedding length. A mismatch breaks relevance silently or errors loudly; count the vector you send.
3. numCandidates vs limit. Too low and recall collapses (good docs never surface); way too high and latency balloons.
4. filter fields: are they declared type: "filter" in the index? Undeclared filters either error or get ignored.

When to use this

• You are seeing this exact error message; match the block above, not just part of it.
• The failing call matches the scenario in the title: Atlas.
• You want the fastest verified fix before digging through logs.

When not to use this

• Your error text differs from the block above; close cousins often have different causes.
• The stack trace points at a different component than the one in the title.
• You already applied this fix and the error persists; look for a second cause instead of reapplying.

Compatibility

• Not pinned to a specific version; follows current Atlas behavior.

Also seen as

• `in the index? Undeclared filters either error or get ignored.

Confirm

Run the same query with`

Vector search index options (numDimensions, similarity, filter fields) and query options (numCandidates, limit) per the MongoDB Atlas Search docs at https://www.mongodb.com/docs/search/indexes/manage-indexes/, verified 2026-09-26.