BerriAI/litellm · error · ValueError

Valkey semantic-cache index '{self.index_name}' already exis

Error message

Valkey semantic-cache index '{self.index_name}' already exists with embedding dimension {existing_dim}, but the configured embedding model produced dimension {dim}. Use a different valkey_semantic_cache_index_name or drop the existing index.

What it means

On first use the cache creates a valkey-search index whose vector dimension must match the embedding model. If an index with the same name already exists and its stored dimension differs from the dimension the currently configured model produces, _assert_dim_matches raises this ValueError. This protects against mixing embedding models in one index, which would make similarity search meaningless or error out at query time.

Source

Thrown at litellm/caching/valkey_semantic_cache.py:155

    @staticmethod
    def _extract_index_dim(info: dict) -> int | None:
        # FT.INFO nests the vector field's "dimensions" one level inside its
        # "index" block, so flatten each field descriptor a single level and
        # scan for the dimensions marker.
        for field in info.get("attributes") or []:
            if not isinstance(field, (list, tuple)):
                continue
            flat = [sub for item in field for sub in (item if isinstance(item, (list, tuple)) else [item])]
            for i, marker in enumerate(flat):
                if marker in (b"dimensions", "dimensions") and i + 1 < len(flat):
                    return int(flat[i + 1])
        return None

    def _assert_dim_matches(self, info: dict, dim: int) -> None:
        existing_dim: Final = self._extract_index_dim(info)
        if existing_dim is not None and existing_dim != dim:
            raise ValueError(
                f"Valkey semantic-cache index '{self.index_name}' already exists with "
                f"embedding dimension {existing_dim}, but the configured embedding "
                f"model produced dimension {dim}. Use a different "
                f"valkey_semantic_cache_index_name or drop the existing index."
            )

    def _ensure_index_sync(self, dim: int) -> None:
        if self._index_dim == dim:
            return
        try:
            self.sync_client.ft(self.index_name).create_index(
                self._index_schema(dim), definition=self._index_definition()
            )
        except Exception as exc:
            if not self._is_index_exists_error(exc):
                raise
            self._assert_dim_matches(self.sync_client.ft(self.index_name).info(), dim)
        self._index_dim = dim

View on GitHub (pinned to 6c2dcb801b)

Solutions

Use a new index name per embedding model, e.g. valkey_semantic_cache_index_name='litellm-cache-3-large'
Or drop the existing index: valkey-cli FT.DROPINDEX <index_name> (data keys may need separate deletion) and let the cache recreate it with the new dimension
If you did not intend to change models, revert embedding_model to the one that created the index

Example fix

# before
cache = ValkeySemanticCache(similarity_threshold=0.8,
    embedding_model='text-embedding-3-large',  # dim 3072; index built for 1536
    index_name='litellm-sem-cache')

# after
cache = ValkeySemanticCache(similarity_threshold=0.8,
    embedding_model='text-embedding-3-large',
    index_name='litellm-sem-cache-3large')  # fresh index for new dimension

Defensive patterns

Strategy: validation

Validate before calling

EMBED_DIMS = {'text-embedding-ada-002': 1536, 'text-embedding-3-small': 1536, 'text-embedding-3-large': 3072}

def index_name_for(model: str, base: str = 'litellm-sem-cache') -> str:
    # namespace the index by model so dimensions never collide
    return f"{base}-{model.replace('/', '-')}"

Try / catch

try:
    cache = ValkeySemanticCache(**cfg)
except ValueError as e:
    if 'already exists with embedding dimension' in str(e):
        raise ValueError('Rotate valkey_semantic_cache_index_name or FT.DROPINDEX the old index after embedding-model changes') from e
    raise

Prevention

Include the embedding model name in the index name
Treat embedding-model changes as a cache-migration event: new index name, then expire the old one

When it happens

Trigger: Switching embedding_model (e.g. ada-002 dim 1536 → text-embedding-3-large dim 3072, or to a local model with a different dim) while keeping the same valkey_semantic_cache_index_name; or two deployments with different embedding models sharing one index name against the same Valkey.

Common situations: Upgrading the embedding model in production without rotating the cache index; staging and prod pointing at the same Valkey with different models; changing vector_size config after the index was created.

Related errors

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/18e67616ef35564b. Report an issue: GitHub.