microsoft/semantic-kernel · error · VectorStoreModelException

Vector field '{options.vector_property_name}' not found in t

Error message

Vector field '{options.vector_property_name}' not found in the data model definition.

What it means

Raised by MongoDBAtlasCollection._inner_vector_search (VectorStoreModelException) when `definition.try_get_vector_field(options.vector_property_name)` returns None — i.e. the requested vector property name is not a declared vector field in the data model definition. This is a model-mapping error, not a data error: the connector cannot find where to point the $vectorSearch 'path'.

Source

Thrown at python/semantic_kernel/connectors/mongodb.py:366

        **kwargs: Any,
    ) -> KernelSearchResults[VectorSearchResult[TModel]]:
        if search_type == SearchType.VECTOR:
            return await self._inner_vector_search(options, values, vector, **kwargs)
        if search_type == SearchType.KEYWORD_HYBRID:
            return await self._inner_keyword_hybrid_search(options, values, vector, **kwargs)
        raise VectorStoreOperationException("Vector is required for search.")

    async def _inner_vector_search(
        self,
        options: VectorSearchOptions,
        values: Any | None = None,
        vector: Sequence[float | int] | None = None,
        **kwargs: Any,
    ) -> KernelSearchResults[VectorSearchResult[TModel]]:
        collection = self._get_collection()
        vector_field = self.definition.try_get_vector_field(options.vector_property_name)
        if not vector_field:
            raise VectorStoreModelException(
                f"Vector field '{options.vector_property_name}' not found in the data model definition."
            )
        if not vector:
            vector = await self._generate_vector_from_values(values, options)
        vector_search_query: dict[str, Any] = {
            "limit": options.top + options.skip,
            "index": self.index_name,
            "queryVector": vector,
            "path": vector_field.storage_name or vector_field.name,
        }
        if filter := self._build_filter(options.filter):
            vector_search_query["filter"] = filter if isinstance(filter, dict) else {"$and": filter}

        projection_query: dict[str, int | dict] = {
            field: 1
            for field in self.definition.get_names(
                include_vector_fields=options.include_vectors,
                include_key_field=False,  # _id is always included

View on GitHub (pinned to c028a0c7dc)

Solutions

Set options.vector_property_name to a name declared as a vector field in the record definition.
Ensure your model has a VectorStoreRecordVectorField annotation.
Leave vector_property_name unset to let the connector pick the single declared vector field.

Example fix

// before
await collection.search(search_type=SearchType.VECTOR, options=VectorSearchOptions(vector_property_name='content'))
// after
await collection.search(search_type=SearchType.VECTOR, options=VectorSearchOptions(vector_property_name='embedding'))  // 'embedding' is the annotated vector field

Defensive patterns

Strategy: validation

Validate before calling

vf = collection.definition.try_get_vector_field(options.vector_property_name)
if vf is None:
    raise ValueError(f'{options.vector_property_name!r} is not a declared vector field')
await collection._inner_vector_search(options, vector=emb)

Type guard

def has_vector_field(definition, name: str | None) -> bool:
    return definition.try_get_vector_field(name) is not None

Try / catch

from semantic_kernel.exceptions.vector_store_exceptions import VectorStoreModelException
try:
    await collection.search(search_type=SearchType.VECTOR, vector=emb, options=options)
except VectorStoreModelException as e:
    if 'not found' in str(e):
        options.vector_property_name = None  # let connector auto-select
    raise

Prevention

Annotate exactly the vector fields you need with VectorStoreRecordVectorField.
Leave vector_property_name unset when there is a single vector field (auto-select).
Use the property name, not the storage_name, in options.

When it happens

Trigger: Calling vector search with options.vector_property_name set to a name that is not annotated as a vector field; or with a model definition that has no vector field at all; or a name/storage_name mismatch. If vector_property_name is None and there is exactly one vector field it is usually auto-selected, so this fires when the name is explicitly wrong or ambiguous.

Common situations: Typo in vector_property_name; field annotated as a data field instead of VectorStoreRecordVectorField; using storage_name in the option instead of the property name; model definition missing the vector field decorator/annotation.

Related errors

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/46cf102825dfe602. Report an issue: GitHub.