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

During vector search on a CosmosMongoCollection, the connector resolves the vector field named in VectorSearchOptions.vector_property_name against the data model. If no such vector field exists, it raises VectorStoreModelException before issuing the query. This is a precondition check; no network call has been made.

Source

Thrown at python/semantic_kernel/connectors/azure_cosmos_db.py:441

                case "vector-ivf":
                    if "numList" in kwargs:
                        index["cosmosSearchOptions"]["numList"] = kwargs["numList"]
            indexes.append(index)

        return {"createIndexes": self.collection_name, "indexes": indexes}

    @override
    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] = {
            "k": options.top + options.skip,
            "index": f"{vector_field.storage_name or vector_field.name}_",
            "vector": vector,
            "path": vector_field.storage_name or vector_field.name,
        }
        if filter := self._build_filter(options.filter):  # type: ignore
            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 VectorSearchOptions.vector_property_name to an existing vector field's name.
If the model has a single vector field, omit vector_property_name or ensure the default resolution works.
Verify spelling and that the field is declared as a vector (not a data) field.

Example fix

// before
options = VectorSearchOptions(vector_property_name="title", top=5)
// after
options = VectorSearchOptions(vector_property_name="embedding", top=5)

Defensive patterns

Strategy: validation

Validate before calling

vf = definition.try_get_vector_field(options.vector_property_name)
if not vf:
    available = [f.name for f in definition.vector_fields]
    raise ValueError(f"Unknown vector field '{options.vector_property_name}'. Available: {available}")

Type guard

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

Prevention

Assert the vector field exists before calling search.
Log available vector field names when constructing search options.
Keep search call sites in sync with model field renames.

When it happens

Trigger: Raised in CosmosMongoCollection._inner_vector_search when definition.try_get_vector_field(options.vector_property_name) returns falsy. Triggered when the caller passes a VectorSearchOptions with a vector_property_name that does not match any VectorStoreRecordVectorField name/storage_name in the model, or when the model has no vector fields at all.

Common situations: Typo in vector_property_name. Passing the data-field name instead of the vector-field name. Searching a model that defines multiple vector fields but referencing one that was removed. Defaulting vector_property_name incorrectly when the model has several vector fields.

Related errors

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