microsoft/semantic-kernel · error · VectorStoreInitializationException

Distance function {field.distance_function} is not supported

Error message

Distance function {field.distance_function} is not supported.

What it means

A VectorStoreInitializationException raised by _create_index() when the vector field's distance_function is not in DISTANCE_FUNCTION_MAP (faiss.py:32-43). That map covers EUCLIDEAN_SQUARED_DISTANCE, DOT_PROD, and DEFAULT (which alias to faiss.IndexFlatL2 / IndexFlatIP). Any other distance metric (cosine, manhattan, hamming) is rejected before attempting to build the index.

Source

Thrown at python/semantic_kernel/connectors/faiss.py:50

logger = logging.getLogger(__name__)

DISTANCE_FUNCTION_MAP: Final[dict[DistanceFunction, type[faiss.Index]]] = {
    DistanceFunction.EUCLIDEAN_SQUARED_DISTANCE: faiss.IndexFlatL2,
    DistanceFunction.DOT_PROD: faiss.IndexFlatIP,
    DistanceFunction.DEFAULT: faiss.IndexFlatL2,
}
INDEX_KIND_MAP: Final[dict[IndexKind, bool]] = {
    IndexKind.FLAT: True,
    IndexKind.DEFAULT: True,
}


def _create_index(field: VectorStoreField) -> faiss.Index:
    """Create a Faiss index."""
    if field.index_kind not in INDEX_KIND_MAP:
        raise VectorStoreInitializationException(f"Index kind {field.index_kind} is not supported.")
    if field.distance_function not in DISTANCE_FUNCTION_MAP:
        raise VectorStoreInitializationException(f"Distance function {field.distance_function} is not supported.")
    match field.index_kind:
        case IndexKind.FLAT | IndexKind.DEFAULT:
            match field.distance_function:
                case DistanceFunction.EUCLIDEAN_SQUARED_DISTANCE | DistanceFunction.DEFAULT:
                    return faiss.IndexFlatL2(field.dimensions)
                case DistanceFunction.DOT_PROD:
                    return faiss.IndexFlatIP(field.dimensions)
                case _:
                    raise VectorStoreInitializationException(
                        f"Distance function {field.distance_function} is "
                        f"not supported for index kind {field.index_kind}."
                    )
        case _:
            raise VectorStoreInitializationException(f"Index with {field.index_kind} is not supported.")


class FaissCollection(InMemoryCollection[TKey, TModel], Generic[TKey, TModel]):
    """Create a Faiss collection.

View on GitHub (pinned to c028a0c7dc)

Solutions

  1. Use DistanceFunction.DOT_PROD with L2-normalized embeddings to emulate cosine similarity.
  2. Or use DistanceFunction.EUCLIDEAN_SQUARED_DISTANCE / DEFAULT for L2 search.
  3. If a specific metric is mandatory, build the faiss.Index yourself and pass it via the 'index'/'indexes' parameter.

Example fix

// before
VectorStoreRecordVectorField(name="embedding", distance_function=DistanceFunction.COSINE_SIMILARITY, dimensions=1536)
// after
# normalize embeddings upstream, then use dot product
VectorStoreRecordVectorField(name="embedding", distance_function=DistanceFunction.DOT_PROD, dimensions=1536)
Defensive patterns

Strategy: validation

Validate before calling

from semantic_kernel.connectors.faiss import DISTANCE_FUNCTION_MAP
assert all(f.distance_function in DISTANCE_FUNCTION_MAP for f in definition.vector_fields), (
    f"Faiss supports only: {[k.value for k in DISTANCE_FUNCTION_MAP]}"
)

Type guard

from semantic_kernel.data.vector import DistanceFunction
from semantic_kernel.connectors.faiss import DISTANCE_FUNCTION_MAP

def is_faiss_distance(df: DistanceFunction) -> bool:
    return df in DISTANCE_FUNCTION_MAP

Try / catch

from semantic_kernel.exceptions import VectorStoreInitializationException
try:
    FaissCollection(record_type=Doc)
except VectorStoreInitializationException as e:
    if "Distance function" in str(e):
        # switch to DOT_PROD and normalize vectors, or use EUCLIDEAN_SQUARED_DISTANCE
        ...

Prevention

When it happens

Trigger: Defining a vector field with a distance_function like DistanceFunction.COSINE_SIMILARITY (or MANHATTAN/HAMMING) and letting FaissCollection auto-build the index.

Common situations: Using cosine similarity for normalized embeddings — Faiss does not have a native cosine IndexFlat, so the connector rejects it; users must normalize vectors and use DOT_PROD, or implement L2-normalization upstream.

Related errors

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