microsoft/semantic-kernel · error · VectorStoreModelException

Distance function '{vector_field.distance_function}' is not

Error message

Distance function '{vector_field.distance_function}' is not supported by Azure Cosmos DB NoSQL.

What it means

During NoSQL vector search, the connector validates that the resolved vector field's distance function is in the NoSQL-supported map before building the VectorDistance clause. If the model declares an unsupported metric, the search fails fast with VectorStoreModelException. This mirrors the policy-time check (error 1240) but at query time.

Source

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

                    rename[parameter["name"]] = new_name
                    params.append({"name": new_name, "value": parameter["value"]})
                if rename:

                    def _substitute(match: "re.Match[str]", mapping: dict[str, str] = rename) -> str:
                        return mapping[match.group(0)]

                    clause = re.sub(r"@filter_p\d+", _substitute, clause)
                rendered_clauses.append(clause)
            where_clauses = (
                f"WHERE {rendered_clauses[0]} "
                if len(rendered_clauses) == 1
                else f"WHERE ({' AND '.join(rendered_clauses)}) "
            )
        vector_field_name = vector_field.storage_name or vector_field.name
        select_clause = self._build_select_clause(options.include_vectors)
        params.append({"name": "@vector", "value": vector})
        if vector_field.distance_function not in DISTANCE_FUNCTION_MAP_NOSQL:
            raise VectorStoreModelException(
                f"Distance function '{vector_field.distance_function}' is not supported by Azure Cosmos DB NoSQL."
            )
        # Cosmos DB VectorDistance function only accepts 2 parameters: field and vector
        # Distance function is configured in the vector index, not in the query
        if search_type == SearchType.VECTOR:
            distance_clause = f"VectorDistance(c.{vector_field_name}, @vector)"
        elif search_type == SearchType.KEYWORD_HYBRID:
            # Hybrid search: requires both a vector and keywords
            params.append({"name": "@keywords", "value": values})
            text_field = options.additional_property_name
            if not text_field:
                raise VectorStoreModelException("Hybrid search requires 'keyword_field_name' in options.")
            distance_clause = (
                f"RRF(VectorDistance(c.{vector_field_name}, @vector), FullTextScore(c.{text_field}, @keywords))"
            )
        else:
            raise VectorStoreModelException(f"Search type '{search_type}' is not supported.")
        query = (

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Set the vector field's distance_function to a supported value (cosine, dot product, euclidean, default).
2. Keep the model consistent with what was used to create the index.
3. If you need another metric, choose a connector/data model that supports it.

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_NOSQL

for f in definition.vector_fields:
    if f.distance_function not in DISTANCE_FUNCTION_MAP_NOSQL:
        raise ValueError(f"Field '{f.name}' has unsupported distance function {f.distance_function}")

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

When it happens

Trigger: Raised in _inner_search when vector_field.distance_function not in DISTANCE_FUNCTION_MAP_NOSQL. Triggered when the data model's vector field uses a DistanceFunction not supported by NoSQL (anything outside COSINE_SIMILARITY, DOT_PROD, EUCLIDEAN_DISTANCE, DEFAULT).

Common situations: Sharing a model definition with a connector that permits a wider metric set. Manually mutating the distance_function after construction. Inconsistent definitions between two deployments.

Related errors

• 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
• Index kind '{field.index_kind}' is not supported by Azure Co
• Distance function '{field.distance_function}' is not support

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