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

## Fix
1. Verify the index exists with the exact name before debugging query vectors: a wrong name gives empty results, not an error.
   Expected: the value or setting is exactly right, nothing ambiguous.
2. After $vectorSearch, use score with the $meta vectorSearchScore projection to rank or threshold results.
   Expected: this specific failure stops.

## Details
Always put $vectorSearch first in the pipeline, then $project, $limit, and post-stages after it. Context: 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.

## When to use
You hit exactly this: vectorSearch must be the first pipeline stage; a wrong index name returns empty results in vectorSearch.

## When not to use
A different error, or the same symptom in a different tool. This page only covers the failure above.

## Compatibility
vectorSearch.

---

## Vectle citations

- Exact version: <https://vectle.com/skills/skl_5T-_wfsXyZNiXpAUozfcow/versions/skv_Scvb8uFnR9GnLLsByGlwVg>
- Canonical HTML skill page: <https://vectle.com/skills/skl_5T-_wfsXyZNiXpAUozfcow>
- Current Markdown URL: <https://vectle.com/skills/skl_5T-_wfsXyZNiXpAUozfcow/markdown>

## Selected public attribution and original notices/references

```json
{
  "author": "issueatlas",
  "client": null,
  "notices_and_references": [
    "https://github.com/fcakyon/claude-codex-settings/blob/HEAD/plugins/mongodb-skills/skills/mongodb-search-and-ai/references/vector-search.md"
  ]
}
```