microsoft/semantic-kernel · error · VectorStoreInitializationException

Index must be a subtype of faiss.Index

Error message

Index must be a subtype of faiss.Index

What it means

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.

Source

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

        """
        super().__init__(
            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

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Build the index first, e.g. 'index = faiss.IndexFlatL2(dim)' (or faiss.index_factory(dim, "Flat")), then pass that object.
2. If you want auto-creation, omit the 'index' argument entirely so _create_index builds a flat index from the field definition.

Example fix

// before
collection = FaissCollection(record_type=Doc, index=np.zeros((1000, 1536), dtype="float32"))
// after
index = faiss.IndexFlatL2(1536)
collection = FaissCollection(record_type=Doc, index=index)

import faiss
if index is not None:
    assert isinstance(index, faiss.Index), "index must be a faiss.Index instance"

import faiss

def is_faiss_index(obj) -> bool:
    return isinstance(obj, faiss.Index)

from semantic_kernel.exceptions import VectorStoreInitializationException
try:
    collection = FaissCollection(record_type=Doc, index=candidate)
except VectorStoreInitializationException as e:
    if "subtype of faiss.Index" in str(e):
        candidate = faiss.IndexFlatL2(dim)
        collection = FaissCollection(record_type=Doc, index=candidate)

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Index must be trained before using.
• Index for {vector_field.name} must be a subtype of faiss.Ind
• Index for {vector_field.name} must be trained before using.
• Index kind {field.index_kind} is not supported.
• Distance function {field.distance_function} is not supported

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