run-llama/llama_index · error · ValueError

embeddings_cache must be defined

Error message

embeddings_cache must be defined

What it means

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.

Source

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

        """
        return await asyncio.gather(
            *[self._aget_text_embedding(text) for text in texts]
        )

    async def _aget_text_embeddings_rate_limited(
        self, texts: List[str]
    ) -> List[Embedding]:
        """Acquire rate limiter before delegating to _aget_text_embeddings."""
        if self.rate_limiter is not None:
            await self.rate_limiter.async_acquire()
        return await self._aget_text_embeddings(texts)

    def _get_text_embeddings_cached(self, texts: List[str]) -> List[Embedding]:
        """
        Get text embeddings from cache. If not in cache, generate them.
        """
        if self.embeddings_cache is None:
            raise ValueError("embeddings_cache must be defined")

        embeddings: List[Optional[Embedding]] = [None for i in range(len(texts))]
        # Tuples of (index, text) to be able to keep same order of embeddings
        non_cached_texts: List[Tuple[int, str]] = []
        for i, txt in enumerate(texts):
            cached_emb = self.embeddings_cache.get(key=txt, collection="embeddings")
            if cached_emb is not None:
                cached_key = next(iter(cached_emb.keys()))
                embeddings[i] = cached_emb[cached_key]
            else:
                non_cached_texts.append((i, txt))
        if len(non_cached_texts) > 0:
            text_embeddings = self._get_text_embeddings(
                [x[1] for x in non_cached_texts]
            )
            for j, text_embedding in enumerate(text_embeddings):
                orig_i = non_cached_texts[j][0]
                embeddings[orig_i] = text_embedding

View on GitHub (pinned to afd0fef371)

Solutions

1. Pass a BaseKVStore (e.g. SimpleKVStore, RedisKVStore) as embeddings_cache when constructing the embed model.
2. If you don't want caching, disable the code path that requests cached embeddings instead of leaving cache None.
3. Set a default at startup: if embed_model.embeddings_cache is None: embed_model.embeddings_cache = SimpleKVStore().

Example fix

# before
embed_model = OpenAIEmbedding()  # later hits cached path -> ValueError

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

if embed_model.embeddings_cache is None:
    from llama_index.core.storage.kvstore import SimpleKVStore
    embed_model.embeddings_cache = SimpleKVStore()

When it happens

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

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

Related errors

• embeddings_cache must be of type BaseKVStore
• No embeddings to aggregate
• Did not find {key}, please add an environment variable `{env
• Cannot add two handlers of the same type {type(new_handler)}
• The embedding file {file_path} is empty.

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