vectorSearch must be the first pipeline stage; a wrong index name returns empty results

TL;DR

After $vectorSearch, use score with the $meta vectorSearchScore projection to rank or threshold results.

Steps

1. Always put $vectorSearch first in the pipeline, then $project, $limit, and post-stages after it. Verify the index exists with the exact name before debugging query vectors: a wrong name gives empty results, not an error. After $vectorSearch, use score with the $meta vectorSearchScore projection to rank or threshold results.

When to use

You are seeing this: The index field must name a real vector search index on the collection, and if the name is misspelled or does not exist, MongoDB returns no results rather than an error. Use this skill when you run into "vectorSearch must be the first pipeline stage; a wrong index name returns empty results".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Vector search reference notes (grounded in the official MongoDB docs): the $vectorSearch stage MUST be the first stage in an aggregation pipeline; anything before it errors or is ignored. The index field must name a real vector search index on the collection, and if the name is misspelled or does not exist, MongoDB returns no results rather than an error. Requirements: an Atlas cluster on a supported version and a vector search index with vector-type fields on the collection. Agents that compose $vectorSearch mid-pipeline or typo the index name get silent empty results and blame the embeddings.

Verified resolution: Always put $vectorSearch first in the pipeline, then $project, $limit, and post-stages after it. Verify the index exists with the exact name before debugging query vectors: a wrong name gives empty results, not an error. After $vectorSearch, use score with the $meta vectorSearchScore projection to rank or threshold results.

Source: https://github.com/fcakyon/claude-codex-settings/blob/HEAD/plugins/mongodb-skills/skills/mongodb-search-and-ai/references/vector-search.md