{"record":{"id":"b05949d6668518ee","repo":"microsoft/semantic-kernel","slug":"distance-function-field-distance-function-is-not","errorCode":null,"errorMessage":"Distance function {field.distance_function} is not supported.","messagePattern":"Distance function (.+?) is not supported\\.","errorType":"exception","errorClass":"VectorStoreInitializationException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/connectors/faiss.py","lineNumber":50,"sourceCode":"logger = logging.getLogger(__name__)\n\nDISTANCE_FUNCTION_MAP: Final[dict[DistanceFunction, type[faiss.Index]]] = {\n    DistanceFunction.EUCLIDEAN_SQUARED_DISTANCE: faiss.IndexFlatL2,\n    DistanceFunction.DOT_PROD: faiss.IndexFlatIP,\n    DistanceFunction.DEFAULT: faiss.IndexFlatL2,\n}\nINDEX_KIND_MAP: Final[dict[IndexKind, bool]] = {\n    IndexKind.FLAT: True,\n    IndexKind.DEFAULT: True,\n}\n\n\ndef _create_index(field: VectorStoreField) -> faiss.Index:\n    \"\"\"Create a Faiss index.\"\"\"\n    if field.index_kind not in INDEX_KIND_MAP:\n        raise VectorStoreInitializationException(f\"Index kind {field.index_kind} is not supported.\")\n    if field.distance_function not in DISTANCE_FUNCTION_MAP:\n        raise VectorStoreInitializationException(f\"Distance function {field.distance_function} is not supported.\")\n    match field.index_kind:\n        case IndexKind.FLAT | IndexKind.DEFAULT:\n            match field.distance_function:\n                case DistanceFunction.EUCLIDEAN_SQUARED_DISTANCE | DistanceFunction.DEFAULT:\n                    return faiss.IndexFlatL2(field.dimensions)\n                case DistanceFunction.DOT_PROD:\n                    return faiss.IndexFlatIP(field.dimensions)\n                case _:\n                    raise VectorStoreInitializationException(\n                        f\"Distance function {field.distance_function} is \"\n                        f\"not supported for index kind {field.index_kind}.\"\n                    )\n        case _:\n            raise VectorStoreInitializationException(f\"Index with {field.index_kind} is not supported.\")\n\n\nclass FaissCollection(InMemoryCollection[TKey, TModel], Generic[TKey, TModel]):\n    \"\"\"Create a Faiss collection.","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/connectors/faiss.py#L32-L68","documentation":"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.","triggerScenarios":"Defining a vector field with a distance_function like DistanceFunction.COSINE_SIMILARITY (or MANHATTAN/HAMMING) and letting FaissCollection auto-build the index.","commonSituations":"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.","solutions":["Use DistanceFunction.DOT_PROD with L2-normalized embeddings to emulate cosine similarity.","Or use DistanceFunction.EUCLIDEAN_SQUARED_DISTANCE / DEFAULT for L2 search.","If a specific metric is mandatory, build the faiss.Index yourself and pass it via the 'index'/'indexes' parameter."],"exampleFix":"// before\nVectorStoreRecordVectorField(name=\"embedding\", distance_function=DistanceFunction.COSINE_SIMILARITY, dimensions=1536)\n// after\n# normalize embeddings upstream, then use dot product\nVectorStoreRecordVectorField(name=\"embedding\", distance_function=DistanceFunction.DOT_PROD, dimensions=1536)","handlingStrategy":"validation","validationCode":"from semantic_kernel.connectors.faiss import DISTANCE_FUNCTION_MAP\nassert all(f.distance_function in DISTANCE_FUNCTION_MAP for f in definition.vector_fields), (\n    f\"Faiss supports only: {[k.value for k in DISTANCE_FUNCTION_MAP]}\"\n)","typeGuard":"from semantic_kernel.data.vector import DistanceFunction\nfrom semantic_kernel.connectors.faiss import DISTANCE_FUNCTION_MAP\n\ndef is_faiss_distance(df: DistanceFunction) -> bool:\n    return df in DISTANCE_FUNCTION_MAP","tryCatchPattern":"from semantic_kernel.exceptions import VectorStoreInitializationException\ntry:\n    FaissCollection(record_type=Doc)\nexcept VectorStoreInitializationException as e:\n    if \"Distance function\" in str(e):\n        # switch to DOT_PROD and normalize vectors, or use EUCLIDEAN_SQUARED_DISTANCE\n        ...","preventionTips":["Emulate cosine via DOT_PROD on L2-normalized embeddings.","Pre-normalize embeddings upstream when using dot product for similarity."],"tags":["faiss","vector-store","configuration","distance-function"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}