What causes "Index for {vector_field.name} must be trained before using." in microsoft/semantic-kernel?

Train each index on representative data before adding it to the 'indexes' dict: index.train(training_array.astype('float32')).

microsoft/semantic-kernel · error · VectorStoreInitializationException

Index for {vector_field.name} must be trained before using.

Error message

Index for {vector_field.name} must be trained before using.

What it means

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.

Source

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

        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)
            if vector_field.name not in self.indexes_key_map:
                self.indexes_key_map.setdefault(vector_field.name, {})

    @override
    async def ensure_collection_exists(
        self, index: faiss.Index | None = None, indexes: dict[str, faiss.Index] | None = None, **kwargs: Any
    ) -> None:
        """Create a collection.

        Considering the complexity of different faiss indexes, we support a limited set.

View on GitHub (pinned to c028a0c7dc)

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.

Example fix

// before
idx_b = faiss.IndexIVFFlat(faiss.IndexFlatL2(300), 300, 64)
collection = FaissCollection(record_type=Doc, indexes={"vec_b": idx_b})  # untrained
// after
idx_b = faiss.IndexIVFFlat(faiss.IndexFlatL2(300), 300, 64)
idx_b.train(train_vectors_b.astype("float32"))
collection = FaissCollection(record_type=Doc, indexes={"vec_b": idx_b})

Defensive patterns

Strategy: validation

Validate before calling

untrained = {name: obj for name, obj in (indexes or {}).items() if not obj.is_trained}
assert not untrained, f"Train these indexes before use: {list(untrained)}"

Type guard

def all_indexes_trained(indexes: dict) -> bool:
    return all(v.is_trained for v in indexes.values())

Try / catch

from semantic_kernel.exceptions import VectorStoreInitializationException
try:
    collection = FaissCollection(record_type=Doc, indexes=indexes)
except VectorStoreInitializationException as e:
    if "must be trained" in str(e):
        for name, idx in indexes.items():
            if not idx.is_trained:
                idx.train(train_data[name].astype("float32"))
        collection = FaissCollection(record_type=Doc, indexes=indexes)

Prevention

Train every approximate index before adding it to the 'indexes' dict.
Use IndexFlat* for fields lacking training data.

When it happens

Trigger: Passing FaissCollection(..., indexes={"vec": <untrained IVF/PQ index>}) for a multi-vector model without calling .train() on that index first.

Common situations: Building several approximate indexes for multiple embedding spaces and forgetting to train one of them; assuming the connector trains supplied indexes (it does not).

Related errors

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