{"record":{"id":"5df3828949c841f6","repo":"run-llama/llama_index","slug":"embeddings-cache-must-be-defined","errorCode":null,"errorMessage":"embeddings_cache must be defined","messagePattern":"embeddings_cache must be defined","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"llama-index-core/llama_index/core/base/embeddings/base.py","lineNumber":323,"sourceCode":"        \"\"\"\n        return await asyncio.gather(\n            *[self._aget_text_embedding(text) for text in texts]\n        )\n\n    async def _aget_text_embeddings_rate_limited(\n        self, texts: List[str]\n    ) -> List[Embedding]:\n        \"\"\"Acquire rate limiter before delegating to _aget_text_embeddings.\"\"\"\n        if self.rate_limiter is not None:\n            await self.rate_limiter.async_acquire()\n        return await self._aget_text_embeddings(texts)\n\n    def _get_text_embeddings_cached(self, texts: List[str]) -> List[Embedding]:\n        \"\"\"\n        Get text embeddings from cache. If not in cache, generate them.\n        \"\"\"\n        if self.embeddings_cache is None:\n            raise ValueError(\"embeddings_cache must be defined\")\n\n        embeddings: List[Optional[Embedding]] = [None for i in range(len(texts))]\n        # Tuples of (index, text) to be able to keep same order of embeddings\n        non_cached_texts: List[Tuple[int, str]] = []\n        for i, txt in enumerate(texts):\n            cached_emb = self.embeddings_cache.get(key=txt, collection=\"embeddings\")\n            if cached_emb is not None:\n                cached_key = next(iter(cached_emb.keys()))\n                embeddings[i] = cached_emb[cached_key]\n            else:\n                non_cached_texts.append((i, txt))\n        if len(non_cached_texts) > 0:\n            text_embeddings = self._get_text_embeddings(\n                [x[1] for x in non_cached_texts]\n            )\n            for j, text_embedding in enumerate(text_embeddings):\n                orig_i = non_cached_texts[j][0]\n                embeddings[orig_i] = text_embedding","sourceCodeStart":305,"sourceCodeEnd":341,"githubUrl":"https://github.com/run-llama/llama_index/blob/afd0fef371831f9bda13e5af7167cf4e981278ab/llama-index-core/llama_index/core/base/embeddings/base.py#L305-L341","documentation":"Raised by the synchronous _get_text_embeddings_cached when embeddings_cache is None. This internal method is only reached when caching was requested (e.g. via a cachable embedding flow), but the embed model was constructed without a valid embeddings_cache kvstore, so it fails fast.","triggerScenarios":"Constructing an embed model without embeddings_cache and then invoking the cached text-embedding path (e.g. get_text_embedding_batch with caching enabled, or a component like a cached embed pipeline calling _get_text_embeddings_cached).","commonSituations":"Enabling embedding caching in Settings or a pipeline while forgetting to attach a kvstore; toggling is_cached/enable caching flags after the embed model was already created; upgrade where the cache default changed to None.","solutions":["Pass a BaseKVStore (e.g. SimpleKVStore, RedisKVStore) as embeddings_cache when constructing the embed model.","If you don't want caching, disable the code path that requests cached embeddings instead of leaving cache None.","Set a default at startup: if embed_model.embeddings_cache is None: embed_model.embeddings_cache = SimpleKVStore()."],"exampleFix":"# before\nembed_model = OpenAIEmbedding()  # later hits cached path -> ValueError\n\n# after\nfrom llama_index.core.storage.kvstore import SimpleKVStore\nembed_model = OpenAIEmbedding(embeddings_cache=SimpleKVStore())","handlingStrategy":"validation","validationCode":"if embed_model.embeddings_cache is None:\n    from llama_index.core.storage.kvstore import SimpleKVStore\n    embed_model.embeddings_cache = SimpleKVStore()","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always construct embed models with embeddings_cache when using cached paths.","Centralize embed-model construction in one factory so the cache is never forgotten."],"tags":["llama-index","embeddings","cache","config"],"backgroundTag":null,"analyzedSha":"afd0fef371831f9bda13e5af7167cf4e981278ab","analyzedAt":"2026-08-15T05:42:58.429Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}