{"record":{"id":"891b235acffaf0ea","repo":"microsoft/semantic-kernel","slug":"index-must-be-trained-before-using","errorCode":null,"errorMessage":"Index must be trained before using.","messagePattern":"Index must be trained before using\\.","errorType":"exception","errorClass":"VectorStoreInitializationException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/connectors/faiss.py","lineNumber":123,"sourceCode":"            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\n            if vector_field.name not in self.indexes:\n                self.indexes[vector_field.name] = _create_index(vector_field)","sourceCodeStart":105,"sourceCodeEnd":141,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/connectors/faiss.py#L105-L141","documentation":"A VectorStoreInitializationException raised in the single-vector-field path of _create_indexes() when the supplied faiss.Index reports index.is_trained == False. Faiss approximate indexes (IVF, IVFPQ, etc.) must be trained on representative data before use; an untrained index would produce incorrect search results, so the connector refuses it.","triggerScenarios":"Instantiating an index that requires training (e.g. faiss.IndexIVFFlat, faiss.IndexIVFPQ) and passing it to FaissCollection without calling index.train(data) first.","commonSituations":"Using IVF/PQ for large-scale search and forgetting the train() step; assuming IndexFlat (which needs no training) behavior for all index types.","solutions":["Train the index before passing it: gather a representative numpy float32 array and call 'index.train(training_data)'.","Or use an index that needs no training (faiss.IndexFlatL2 / IndexFlatIP) if you cannot provide training data."],"exampleFix":"// before\nquantizer = faiss.IndexFlatL2(1536)\nindex = faiss.IndexIVFFlat(quantizer, 1536, 100)\ncollection = FaissCollection(record_type=Doc, index=index)  # not trained\n// after\nquantizer = faiss.IndexFlatL2(1536)\nindex = faiss.IndexIVFFlat(quantizer, 1536, 100)\nindex.train(training_vectors.astype(\"float32\"))\ncollection = FaissCollection(record_type=Doc, index=index)","handlingStrategy":"validation","validationCode":"if index is not None and not index.is_trained:\n    raise ValueError(\"Train the index before passing it to FaissCollection\")","typeGuard":"def is_trained_faiss_index(obj) -> bool:\n    import faiss\n    return isinstance(obj, faiss.Index) and obj.is_trained","tryCatchPattern":"from semantic_kernel.exceptions import VectorStoreInitializationException\ntry:\n    collection = FaissCollection(record_type=Doc, index=candidate)\nexcept VectorStoreInitializationException as e:\n    if \"must be trained\" in str(e):\n        candidate.train(train_data.astype(\"float32\"))\n        collection = FaissCollection(record_type=Doc, index=candidate)","preventionTips":["Call index.train(representative_data) for IVF/PQ indexes before use.","Use IndexFlatL2/IndexFlatIP when no training data is available."],"tags":["faiss","vector-store","configuration","index","training"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}