{"record":{"id":"b34d43102f50ec12","repo":"run-llama/llama_index","slug":"embeddings-cache-must-be-of-type-basekvstore","errorCode":null,"errorMessage":"embeddings_cache must be of type BaseKVStore","messagePattern":"embeddings_cache must be of type BaseKVStore","errorType":"exception","errorClass":"TypeError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/base/embeddings/base.py","lineNumber":129,"sourceCode":"        never contain credentials (e.g. ``api_key``) or auth headers. Subclasses\n        may override to add safe details.\n        \"\"\"\n        return {\n            \"class_name\": self.class_name(),\n            \"model_name\": self.model_name,\n            \"embed_batch_size\": self.embed_batch_size,\n        }\n\n    @model_validator(mode=\"after\")\n    def check_base_embeddings_class(self) -> Self:\n        from llama_index.core.storage.kvstore.types import BaseKVStore\n\n        if self.callback_manager is None:\n            self.callback_manager = CallbackManager([])\n        if self.embeddings_cache is not None and not isinstance(\n            self.embeddings_cache, BaseKVStore\n        ):\n            raise TypeError(\"embeddings_cache must be of type BaseKVStore\")\n        return self\n\n    @abstractmethod\n    def _get_query_embedding(self, query: str) -> Embedding:\n        \"\"\"\n        Embed the input query synchronously.\n\n        Subclasses should implement this method. Reference get_query_embedding's\n        docstring for more information.\n        \"\"\"\n\n    @abstractmethod\n    async def _aget_query_embedding(self, query: str) -> Embedding:\n        \"\"\"\n        Embed the input query asynchronously.\n\n        Subclasses should implement this method. Reference get_query_embedding's\n        docstring for more information.","sourceCodeStart":111,"sourceCodeEnd":147,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/base/embeddings/base.py#L111-L147","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["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.","If you wrote a custom cache, subclass BaseKVStore and implement get/put/async variants, then pass it.","Leave embeddings_cache=None if you don't want caching at all."],"exampleFix":"# before\nembed_model = OpenAIEmbedding(embeddings_cache=my_plain_dict)\n\n# after\nfrom llama_index.core.storage.kvstore import SimpleKVStore\nembed_model = OpenAIEmbedding(embeddings_cache=SimpleKVStore())","handlingStrategy":"type-guard","validationCode":"from llama_index.core.storage.kvstore.types import BaseKVStore\nassert embeddings_cache is None or isinstance(embeddings_cache, BaseKVStore)","typeGuard":"def is_valid_kvstore(c: Any) -> bool:\n    from llama_index.core.storage.kvstore.types import BaseKVStore\n    return c is None or isinstance(c, BaseKVStore)","tryCatchPattern":null,"preventionTips":["Only use kvstore classes from llama_index.core.storage.kvstore or its integrations.","Wrap custom caches as BaseKVStore subclasses."],"tags":["llama-index","embeddings","cache","type-validation","config"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}