run-llama/llama_index · error · TypeError

embeddings_cache must be of type BaseKVStore

Error message

embeddings_cache must be of type BaseKVStore

What it means

Raised by the model validator on BaseEmbedding when the embeddings_cache field is set to something that is not an instance of BaseKVStore (the kvstore abstraction used for caching embeddings). This is a configuration type check that fires at model construction/validation time, not at embed time.

Source

Thrown at llama-index-core/llama_index/core/base/embeddings/base.py:129

        never contain credentials (e.g. ``api_key``) or auth headers. Subclasses
        may override to add safe details.
        """
        return {
            "class_name": self.class_name(),
            "model_name": self.model_name,
            "embed_batch_size": self.embed_batch_size,
        }

    @model_validator(mode="after")
    def check_base_embeddings_class(self) -> Self:
        from llama_index.core.storage.kvstore.types import BaseKVStore

        if self.callback_manager is None:
            self.callback_manager = CallbackManager([])
        if self.embeddings_cache is not None and not isinstance(
            self.embeddings_cache, BaseKVStore
        ):
            raise TypeError("embeddings_cache must be of type BaseKVStore")
        return self

    @abstractmethod
    def _get_query_embedding(self, query: str) -> Embedding:
        """
        Embed the input query synchronously.

        Subclasses should implement this method. Reference get_query_embedding's
        docstring for more information.
        """

    @abstractmethod
    async def _aget_query_embedding(self, query: str) -> Embedding:
        """
        Embed the input query asynchronously.

        Subclasses should implement this method. Reference get_query_embedding's
        docstring for more information.

View on GitHub (pinned to afd0fef371)

Solutions

1. Use a BaseKVStore implementation: from llama_index.core.storage.kvstore import SimpleKVStore (or MongoKVStore/RedisKVStore from their integration packages) and pass that as embeddings_cache.
2. If you wrote a custom cache, subclass BaseKVStore and implement get/put/async variants, then pass it.
3. Leave embeddings_cache=None if you don't want caching at all.

Example fix

# before
embed_model = OpenAIEmbedding(embeddings_cache=my_plain_dict)

# after
from llama_index.core.storage.kvstore import SimpleKVStore
embed_model = OpenAIEmbedding(embeddings_cache=SimpleKVStore())

from llama_index.core.storage.kvstore.types import BaseKVStore
assert embeddings_cache is None or isinstance(embeddings_cache, BaseKVStore)

def is_valid_kvstore(c: Any) -> bool:
    from llama_index.core.storage.kvstore.types import BaseKVStore
    return c is None or isinstance(c, BaseKVStore)

When it happens

Trigger: Constructing an embedding class with embeddings_cache=<arbitrary object>, e.g. a Redis client, a plain dict, a diskcache object, or a custom class that does not subclass BaseKVStore.

Common situations: Assuming any cache-like object works; passing a kvstore client from another library version whose class identity differs; wiring embeddings_cache before realizing it must come from llama_index.core.storage.kvstore (e.g. RedisKVStore, SimpleKVStore).

Related errors

• embeddings_cache must be defined
• Unexpected type: {type(choice)}
• Unexpected type: {type(query)}
• No embeddings to aggregate
• Invalid message content: {message.content!s}

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/b34d43102f50ec12. Report an issue: GitHub.