microsoft/semantic-kernel · error · VectorStoreInitializationException

Index for {vector_field.name} must be a subtype of faiss.Ind

Error message

Index for {vector_field.name} must be a subtype of faiss.Index

What it means

A VectorStoreInitializationException raised in the multi-vector-field path of _create_indexes() when an entry in the 'indexes' dict (keyed by vector field name) is not an instance of faiss.Index. This is the per-field equivalent of error 1296: each supplied index object must be a real faiss.Index.

Source

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

    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)
            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

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Ensure every value in the 'indexes' dict is an instance of faiss.Index built via faiss.IndexFlat*/index_factory.
2. Omit any field you want auto-created from the dict so _create_index builds a flat index for it.

Example fix

// before
collection = FaissCollection(record_type=Doc, indexes={"vec1": faiss.IndexFlatL2(1536), "vec2": matrix})
// after
collection = FaissCollection(record_type=Doc, indexes={"vec1": faiss.IndexFlatL2(1536), "vec2": faiss.IndexFlatIP(300)})

import faiss
bad = {name: obj for name, obj in (indexes or {}).items() if not isinstance(obj, faiss.Index)}
assert not bad, f"These indexes are not faiss.Index: {list(bad)}"

import faiss

def all_indexes_are_faiss(indexes: dict) -> bool:
    return all(isinstance(v, faiss.Index) for v in indexes.values())

from semantic_kernel.exceptions import VectorStoreInitializationException
try:
    collection = FaissCollection(record_type=Doc, indexes=indexes)
except VectorStoreInitializationException as e:
    if "must be a subtype of faiss.Index" in str(e):
        for k, v in indexes.items():
            if not isinstance(v, faiss.Index):
                indexes[k] = faiss.IndexFlatL2(dims[k])
        collection = FaissCollection(record_type=Doc, indexes=indexes)

When it happens

Trigger: Passing FaissCollection(..., indexes={"field_a": <not faiss.Index>}) for a model with multiple vector fields, where one or more values are the wrong type (array, string, dict, etc.).

Common situations: Mixing correctly-built indexes with placeholders/raw data when configuring a multi-vector collection; passing index factory strings per field.

Related errors

• Index for {vector_field.name} must be trained before using.
• Index must be a subtype of faiss.Index
• Index 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/b9f25eaaa37becab. Report an issue: GitHub.