What causes "Index must be trained before using." in microsoft/semantic-kernel?

Train the index before passing it: gather a representative numpy float32 array and call 'index.train(training_data)'.

microsoft/semantic-kernel · error · VectorStoreInitializationException

Index must be trained before using.

Error message

Index must be trained before using.

What it means

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.

Source

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

            record_type=record_type,
            definition=definition,
            collection_name=collection_name,
            embedding_generator=embedding_generator,
            **kwargs,
        )

    def _create_indexes(self, index: faiss.Index | None = None, indexes: dict[str, faiss.Index] | None = None) -> None:
        """Create Faiss indexes for each vector field.

        Args:
            index: The index to use, this can be used when there is only one vector field.
            indexes: A dictionary of indexes, the key is the name of the vector field.
        """
        if len(self.definition.vector_fields) == 1 and index is not None:
            if not isinstance(index, faiss.Index):
                raise VectorStoreInitializationException("Index must be a subtype of faiss.Index")
            if not index.is_trained:
                raise VectorStoreInitializationException("Index must be trained before using.")
            self.indexes[self.definition.vector_fields[0].name] = index
            return
        for vector_field in self.definition.vector_fields:
            if indexes and vector_field.name in indexes:
                if not isinstance(indexes[vector_field.name], faiss.Index):
                    raise VectorStoreInitializationException(
                        f"Index for {vector_field.name} must be a subtype of faiss.Index"
                    )
                if not indexes[vector_field.name].is_trained:
                    raise VectorStoreInitializationException(
                        f"Index for {vector_field.name} must be trained before using."
                    )
                self.indexes[vector_field.name] = indexes[vector_field.name]
                if vector_field.name not in self.indexes_key_map:
                    self.indexes_key_map.setdefault(vector_field.name, {})
                continue
            if vector_field.name not in self.indexes:
                self.indexes[vector_field.name] = _create_index(vector_field)

View on GitHub (pinned to c028a0c7dc)

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.

Example fix

// before
quantizer = faiss.IndexFlatL2(1536)
index = faiss.IndexIVFFlat(quantizer, 1536, 100)
collection = FaissCollection(record_type=Doc, index=index)  # not trained
// after
quantizer = faiss.IndexFlatL2(1536)
index = faiss.IndexIVFFlat(quantizer, 1536, 100)
index.train(training_vectors.astype("float32"))
collection = FaissCollection(record_type=Doc, index=index)

Defensive patterns

Strategy: validation

Validate before calling

if index is not None and not index.is_trained:
    raise ValueError("Train the index before passing it to FaissCollection")

Type guard

def is_trained_faiss_index(obj) -> bool:
    import faiss
    return isinstance(obj, faiss.Index) and obj.is_trained

Try / catch

from semantic_kernel.exceptions import VectorStoreInitializationException
try:
    collection = FaissCollection(record_type=Doc, index=candidate)
except VectorStoreInitializationException as e:
    if "must be trained" in str(e):
        candidate.train(train_data.astype("float32"))
        collection = FaissCollection(record_type=Doc, index=candidate)

Prevention

Call index.train(representative_data) for IVF/PQ indexes before use.
Use IndexFlatL2/IndexFlatIP when no training data is available.

When it happens

Trigger: Instantiating an index that requires training (e.g. faiss.IndexIVFFlat, faiss.IndexIVFPQ) and passing it to FaissCollection without calling index.train(data) first.

Common situations: Using IVF/PQ for large-scale search and forgetting the train() step; assuming IndexFlat (which needs no training) behavior for all index types.

Related errors

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