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 NoSQL.

What it means

This error is raised by the Azure Cosmos DB NoSQL vector embedding policy builder when a vector field's distance function is not in the supported set. Cosmos DB NoSQL only supports cosine similarity, dot product, and Euclidean distance (plus DEFAULT). The check happens at policy-construction time, before any data is written, so it surfaces a data-model definition mismatch.

Source

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

    A default vector embedding policy is created based on the data model definition.

    Args:
        definition (VectorStoreRecordDefinition): The definition of the data model.

    Returns:
        dict[str, Any]: The vector embedding policy.

    Raises:
        VectorStoreModelException: If the datatype or distance function is not supported by Azure Cosmos DB NoSQL.

    """
    vector_embedding_policy: dict[str, Any] = {"vectorEmbeddings": []}

    for field in definition.fields:
        if field.field_type == FieldTypes.VECTOR:
            if field.distance_function not in DISTANCE_FUNCTION_MAP_NOSQL:
                raise VectorStoreModelException(
                    f"Distance function '{field.distance_function}' is not supported by Azure Cosmos DB NoSQL."
                )
            if field.type_ and field.type_ not in VECTOR_DATATYPES_MAP:
                raise VectorStoreModelException(
                    f"Vector property type '{field.type_}' is not supported by Azure Cosmos DB NoSQL."
                )

            vector_embedding_policy["vectorEmbeddings"].append({
                "path": f'/"{field.storage_name or field.name}"',
                "dataType": VECTOR_DATATYPES_MAP[field.type_ or "default"],
                "distanceFunction": DISTANCE_FUNCTION_MAP_NOSQL[field.distance_function],
                "dimensions": field.dimensions,
            })

    return vector_embedding_policy


def _get_key(key: str | CosmosNoSqlCompositeKey) -> str:

View on GitHub (pinned to c028a0c7dc)

Solutions

Set the vector field's distance_function to DistanceFunction.COSINE_SIMILARITY, DistanceFunction.DOT_PROD, DistanceFunction.EUCLIDEAN_DISTANCE, or DistanceFunction.DEFAULT.
If your data genuinely needs an unsupported metric, choose the closest supported one (most embeddings use cosine) or switch to a connector that supports it.
Check the field annotation in your VectorStoreRecordVectorField and correct the distance_function argument.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

from semantic_kernel.data.vector import DistanceFunction
from semantic_kernel.connectors.azure_cosmos_db import DISTANCE_FUNCTION_MAP_NOSQL

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

Type guard

def is_supported_nosql_distance(fn: DistanceFunction) -> bool:
    return fn in DISTANCE_FUNCTION_MAP_NOSQL

Try / catch

try:
    collection = await CosmosNoSqlCollection(...).create()
except VectorStoreModelException as e:
    # fix the data model distance_function
    ...

Prevention

Validate the data model against the connector's supported maps before instantiation.
Centralize vector-field definitions so distance functions are set once and reviewed.
Write a unit test asserting your model's fields are all supported by each connector you use.

When it happens

Trigger: Raised in _get_vector_embedding_policy when field.field_type == FieldTypes.VECTOR and field.distance_function not in DISTANCE_FUNCTION_MAP_NOSQL. This runs when a CosmosNoSqlCollection constructs its container policy (collection creation / protocol negotiation). It triggers when the VectorStoreCollectionDefinition declares a vector field with an unsupported DistanceFunction enum value (e.g. MANHATTAN, JACCARD, HAMMING).

Common situations: Reusing a data model definition written for a different vector store (e.g. Pinecone, Weaviate, Redis) that supports a wider distance-function set. Copying a sample model from another connector. Upgrading semantic-kernel and a previously-tolerated custom distance value is now enumerated.

Related errors

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