{"record":{"id":"f331b73fdb895c60","repo":"microsoft/semantic-kernel","slug":"index-must-be-a-subtype-of-faiss-index","errorCode":null,"errorMessage":"Index must be a subtype of faiss.Index","messagePattern":"Index must be a subtype of faiss\\.Index","errorType":"exception","errorClass":"VectorStoreInitializationException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/connectors/faiss.py","lineNumber":121,"sourceCode":"        \"\"\"\n        super().__init__(\n            record_type=record_type,\n            definition=definition,\n            collection_name=collection_name,\n            embedding_generator=embedding_generator,\n            **kwargs,\n        )\n\n    def _create_indexes(self, index: faiss.Index | None = None, indexes: dict[str, faiss.Index] | None = None) -> None:\n        \"\"\"Create Faiss indexes for each vector field.\n\n        Args:\n            index: The index to use, this can be used when there is only one vector field.\n            indexes: A dictionary of indexes, the key is the name of the vector field.\n        \"\"\"\n        if len(self.definition.vector_fields) == 1 and index is not None:\n            if not isinstance(index, faiss.Index):\n                raise VectorStoreInitializationException(\"Index must be a subtype of faiss.Index\")\n            if not index.is_trained:\n                raise VectorStoreInitializationException(\"Index must be trained before using.\")\n            self.indexes[self.definition.vector_fields[0].name] = index\n            return\n        for vector_field in self.definition.vector_fields:\n            if indexes and vector_field.name in indexes:\n                if not isinstance(indexes[vector_field.name], faiss.Index):\n                    raise VectorStoreInitializationException(\n                        f\"Index for {vector_field.name} must be a subtype of faiss.Index\"\n                    )\n                if not indexes[vector_field.name].is_trained:\n                    raise VectorStoreInitializationException(\n                        f\"Index for {vector_field.name} must be trained before using.\"\n                    )\n                self.indexes[vector_field.name] = indexes[vector_field.name]\n                if vector_field.name not in self.indexes_key_map:\n                    self.indexes_key_map.setdefault(vector_field.name, {})\n                continue","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/connectors/faiss.py#L103-L139","documentation":"A VectorStoreInitializationException raised in FaissCollection._create_indexes() when the definition has exactly one vector field and a single 'index' argument was supplied, but that object is not an instance of faiss.Index. This guards the single-vector convenience path: the caller passed something (a numpy array, a dict, a wrapper) where a trained faiss.Index is required.","triggerScenarios":"Calling FaissCollection(..., index=<not a faiss.Index>) for a single-vector-field model — e.g. passing a numpy ndarray, a tuple (n,d), or a faiss Index factory string instead of an instantiated faiss.Index object.","commonSituations":"Confusing the faiss index factory string ('Flat','IVF') with an index object; passing the raw embedding matrix instead of an index; passing a faiss IndexReplica or custom type not subclassed from faiss.Index.","solutions":["Build the index first, e.g. 'index = faiss.IndexFlatL2(dim)' (or faiss.index_factory(dim, \"Flat\")), then pass that object.","If you want auto-creation, omit the 'index' argument entirely so _create_index builds a flat index from the field definition."],"exampleFix":"// before\ncollection = FaissCollection(record_type=Doc, index=np.zeros((1000, 1536), dtype=\"float32\"))\n// after\nindex = faiss.IndexFlatL2(1536)\ncollection = FaissCollection(record_type=Doc, index=index)","handlingStrategy":"type-guard","validationCode":"import faiss\nif index is not None:\n    assert isinstance(index, faiss.Index), \"index must be a faiss.Index instance\"","typeGuard":"import faiss\n\ndef is_faiss_index(obj) -> bool:\n    return isinstance(obj, faiss.Index)","tryCatchPattern":"from semantic_kernel.exceptions import VectorStoreInitializationException\ntry:\n    collection = FaissCollection(record_type=Doc, index=candidate)\nexcept VectorStoreInitializationException as e:\n    if \"subtype of faiss.Index\" in str(e):\n        candidate = faiss.IndexFlatL2(dim)\n        collection = FaissCollection(record_type=Doc, index=candidate)","preventionTips":["Instantiate indexes with faiss.IndexFlat*/index_factory before passing.","Do not pass raw arrays, tuples, or factory strings as the 'index' argument."],"tags":["faiss","vector-store","configuration","index"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}