microsoft/semantic-kernel · error · VectorStoreModelException

Distance function '{field.distance_function}' is not support

Error message

Distance function '{field.distance_function}' is not supported by Azure Cosmos DB for MongoDB.

What it means

The MongoDB index builder rejects vector fields whose distance function is not in the MongoDB map (COS, IP, L2 / cosine, dot product, euclidean, default). Raised at index-definition construction time, before any write to Cosmos. It is the MongoDB analog of error 1240.

Source

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

        await self._get_database().command(command=self._get_index_definitions(**kwargs))

    def _get_index_definitions(self, **kwargs: Any) -> dict[str, Any]:
        """Creates index definitions for the collection."""
        indexes = [
            {
                "name": f"{field.storage_name or field.name}_",
                FieldTypes.KEY: {field.storage_name or field.name: 1},
            }
            for field in self.definition.data_fields
            if field.is_indexed or field.is_full_text_indexed
        ]
        for field in self.definition.vector_fields:
            if field.index_kind not in INDEX_KIND_MAP_MONGODB:
                raise VectorStoreModelException(
                    f"Index kind '{field.index_kind}' is not supported by Azure Cosmos DB for MongoDB."
                )
            if field.distance_function not in DISTANCE_FUNCTION_MAP_MONGODB:
                raise VectorStoreModelException(
                    f"Distance function '{field.distance_function}' is not supported by Azure Cosmos DB for MongoDB."
                )
            index_name = f"{field.storage_name or field.name}_"
            index_kind = DISTANCE_FUNCTION_MAP_MONGODB[field.distance_function]
            index: dict[str, Any] = {
                "name": index_name,
                FieldTypes.KEY: {field.storage_name or field.name: "cosmosSearch"},
                "cosmosSearchOptions": {
                    "kind": index_kind,
                    "similarity": DISTANCE_FUNCTION_MAP_MONGODB[field.distance_function],
                    "dimensions": field.dimensions,
                },
            }
            match index_kind:
                case "vector-diskann":
                    if "maxDegree" in kwargs:
                        index["cosmosSearchOptions"]["maxDegree"] = kwargs["maxDegree"]
                    if "lBuild" in kwargs:

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Use DistanceFunction.COSINE_SIMILARITY, DOT_PROD, EUCLIDEAN_DISTANCE, or DEFAULT.
2. If the metric truly is unsupported, switch to cosine (most embeddings) or another connector.
3. Maintain per-store definitions rather than one shared model when metrics differ.

Example fix

// before
VectorStoreRecordVectorField(name="embedding", dimensions=1536, distance_function=DistanceFunction.MANHATTAN)
// after
VectorStoreRecordVectorField(name="embedding", dimensions=1536, distance_function=DistanceFunction.COSINE_SIMILARITY)

from semantic_kernel.connectors.azure_cosmos_db import DISTANCE_FUNCTION_MAP_MONGODB

bad = [f for f in definition.vector_fields if f.distance_function not in DISTANCE_FUNCTION_MAP_MONGODB]
if bad:
    raise ValueError(f"Unsupported distance functions: {[f.name for f in bad]}")

def is_supported_mongodb_distance(fn: DistanceFunction) -> bool:
    return fn in DISTANCE_FUNCTION_MAP_MONGODB

When it happens

Trigger: Raised in CosmosMongoCollection._get_index_definitions when field.distance_function not in DISTANCE_FUNCTION_MAP_MONGODB. Fires when a vector field uses a DistanceFunction value outside the four supported ones, e.g. MANHATTAN or a custom enum.

Common situations: Sharing one data-model definition between a NoSQL and a MongoDB collection where the distance function differs in support. Migrating from another store whose distance-function vocabulary is wider. Copying sample code that used an unsupported metric.

Related errors

• Index kind '{field.index_kind}' is not supported by Azure Co
• Vector field '{options.vector_property_name}' not found in t
• Distance function '{field.distance_function}' is not support
• Vector property type '{field.type_}' is not supported by Azu
• Failed to search the collection.

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