BerriAI/litellm · error · ValueError

similarity_threshold must be provided, passed None

Error message

similarity_threshold must be provided, passed None

What it means

ValkeySemanticCache.__init__ mirrors its Redis counterpart: similarity_threshold is mandatory, has no default, and None (or omission) raises ValueError immediately. The threshold is what decides whether a cached answer is 'close enough' to reuse, so the constructor refuses to guess.

Source

Thrown at litellm/caching/valkey_semantic_cache.py:67

    DISTANCE_FIELD_NAME: str = "vector_distance"

    def __init__(
        self,
        host: str | None = None,
        port: str | None = None,
        password: str | None = None,
        redis_url: str | None = None,
        similarity_threshold: float | None = None,
        embedding_model: str = "text-embedding-ada-002",
        index_name: str | None = None,
        ssl: bool = False,
        startup_nodes: list | None = None,
        sync_client: Redis | None = None,
        async_client: AsyncRedis | None = None,
        **kwargs: Any,
    ):
        if similarity_threshold is None:
            raise ValueError("similarity_threshold must be provided, passed None")

        if startup_nodes:
            raise ValueError(
                "valkey-semantic does not support cluster-mode-enabled (multi-shard) "
                "endpoints. The async cluster client cannot route the FT.* search "
                "commands reliably. Point it at a cluster-mode-disabled endpoint "
                "instead (a primary with replicas is fine; only horizontal sharding "
                "is unsupported), or pass a single redis_url. On AWS, vector search "
                "needs ElastiCache for Valkey 8.2+ on a node-based cluster."
            )

        self.similarity_threshold = similarity_threshold
        self.embedding_model = embedding_model
        self.index_name = index_name or self.DEFAULT_VALKEY_INDEX_NAME
        self.key_prefix = f"{self.index_name}:"
        self._index_dim: int | None = None

        resolved_url = None

View on GitHub (pinned to 6c2dcb801b)

Solutions

  1. Pass similarity_threshold explicitly (0.7–0.9 typical), e.g. ValkeySemanticCache(redis_url=..., similarity_threshold=0.8)
  2. Add similarity_threshold to the valkey-semantic cache config block

Example fix

# before
cache = ValkeySemanticCache(redis_url='redis://localhost:6379')

# after
cache = ValkeySemanticCache(redis_url='redis://localhost:6379', similarity_threshold=0.8)
Defensive patterns

Strategy: validation

Validate before calling

if cfg.get('similarity_threshold') is None:
    raise ValueError('valkey semantic cache requires similarity_threshold (e.g. 0.8)')

Prevention

When it happens

Trigger: Constructing litellm.caching.valkey_semantic_cache.ValkeySemanticCache without similarity_threshold; configuring litellm proxy caching with type='valkey-semantic' and omitting the field.

Common situations: Copy-pasting a redis-semantic config block (which already has it) minus the threshold; assuming the Valkey cache shares defaults with the plain RedisCache.

Related errors

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