{"record":{"id":"54e07129d05ecd76","repo":"microsoft/semantic-kernel","slug":"index-for-vector-field-name-must-be-trained-befo","errorCode":null,"errorMessage":"Index for {vector_field.name} must be trained before using.","messagePattern":"Index for (.+?) must be trained before using\\.","errorType":"exception","errorClass":"VectorStoreInitializationException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/connectors/faiss.py","lineNumber":133,"sourceCode":"        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)\n            if vector_field.name not in self.indexes_key_map:\n                self.indexes_key_map.setdefault(vector_field.name, {})\n\n    @override\n    async def ensure_collection_exists(\n        self, index: faiss.Index | None = None, indexes: dict[str, faiss.Index] | None = None, **kwargs: Any\n    ) -> None:\n        \"\"\"Create a collection.\n\n        Considering the complexity of different faiss indexes, we support a limited set.","sourceCodeStart":115,"sourceCodeEnd":151,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/connectors/faiss.py#L115-L151","documentation":"A VectorStoreInitializationException raised in the multi-vector-field path of _create_indexes() when a supplied index for a given vector field reports is_trained == False. It is the per-field equivalent of error 1297: every index passed in the 'indexes' dict must already be trained.","triggerScenarios":"Passing FaissCollection(..., indexes={\"vec\": <untrained IVF/PQ index>}) for a multi-vector model without calling .train() on that index first.","commonSituations":"Building several approximate indexes for multiple embedding spaces and forgetting to train one of them; assuming the connector trains supplied indexes (it does not).","solutions":["Train each index on representative data before adding it to the 'indexes' dict: index.train(training_array.astype('float32')).","Use no-training indexes (IndexFlatL2/IndexFlatIP) for fields where you cannot supply training data."],"exampleFix":"// before\nidx_b = faiss.IndexIVFFlat(faiss.IndexFlatL2(300), 300, 64)\ncollection = FaissCollection(record_type=Doc, indexes={\"vec_b\": idx_b})  # untrained\n// after\nidx_b = faiss.IndexIVFFlat(faiss.IndexFlatL2(300), 300, 64)\nidx_b.train(train_vectors_b.astype(\"float32\"))\ncollection = FaissCollection(record_type=Doc, indexes={\"vec_b\": idx_b})","handlingStrategy":"validation","validationCode":"untrained = {name: obj for name, obj in (indexes or {}).items() if not obj.is_trained}\nassert not untrained, f\"Train these indexes before use: {list(untrained)}\"","typeGuard":"def all_indexes_trained(indexes: dict) -> bool:\n    return all(v.is_trained for v in indexes.values())","tryCatchPattern":"from semantic_kernel.exceptions import VectorStoreInitializationException\ntry:\n    collection = FaissCollection(record_type=Doc, indexes=indexes)\nexcept VectorStoreInitializationException as e:\n    if \"must be trained\" in str(e):\n        for name, idx in indexes.items():\n            if not idx.is_trained:\n                idx.train(train_data[name].astype(\"float32\"))\n        collection = FaissCollection(record_type=Doc, indexes=indexes)","preventionTips":["Train every approximate index before adding it to the 'indexes' dict.","Use IndexFlat* for fields lacking training data."],"tags":["faiss","vector-store","configuration","index","training","multi-vector"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}