BerriAI/litellm · error · ValueError

similarity_threshold must be provided, passed None

Error message

similarity_threshold must be provided, passed None

What it means

RedisSemanticCache.__init__ requires an explicit similarity_threshold; None is rejected with ValueError because the threshold defines when a cached response counts as a semantically equivalent match, and a wrong default would silently return bad cache hits. Unlike the Qdrant cache this is a ValueError, but it behaves the same: raised at construction time.

Source

Thrown at litellm/caching/redis_semantic_cache.py:79

            similarity_threshold: Threshold for semantic similarity (0.0 to 1.0)
                where 1.0 requires exact matches and 0.0 accepts any match
            embedding_model: Model to use for generating embeddings
            index_name: Name for the Redis index
            ttl: Default time-to-live for cache entries in seconds
            **kwargs: Additional arguments passed to the Redis client

        Raises:
            Exception: If similarity_threshold is not provided or required Redis
                connection information is missing
        """
        if index_name is None:
            index_name = self.DEFAULT_REDIS_INDEX_NAME

        print_verbose(f"Redis semantic-cache initializing index - {index_name}")

        # Validate similarity threshold
        if similarity_threshold is None:
            raise ValueError("similarity_threshold must be provided, passed None")

        # Store configuration
        self.similarity_threshold = similarity_threshold

        # Convert similarity threshold [0,1] to distance threshold [0,2]
        # For cosine distance: 0 = most similar, 2 = least similar
        # While similarity: 1 = most similar, 0 = least similar
        self.distance_threshold = 1 - similarity_threshold
        self.embedding_model = embedding_model

        # Set up Redis connection
        if redis_url is None:
            try:
                # Attempt to use provided parameters or fallback to environment variables
                host = host or os.environ["REDIS_HOST"]
                port = port or os.environ["REDIS_PORT"]
                password = password or os.environ["REDIS_PASSWORD"]
            except KeyError as e:

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Pass similarity_threshold explicitly, e.g. RedisSemanticCache(host=..., port=..., password=..., similarity_threshold=0.8)
2. Add similarity_threshold to the redis-semantic cache block in your litellm proxy config

Example fix

# before
cache = RedisSemanticCache(host=h, port=p, password=pw)

# after
cache = RedisSemanticCache(host=h, port=p, password=pw, similarity_threshold=0.8)

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

When it happens

Trigger: Instantiating litellm.caching.redis_semantic_cache.RedisSemanticCache without similarity_threshold (or with None); configuring litellm proxy caching with type='redis-semantic' and omitting the threshold.

Common situations: Adopting the Redis semantic cache from the plain RedisCache and assuming defaults; config YAML written from partial documentation.

Related errors

• collection_name must be provided, passed None
• similarity_threshold must be provided, passed None
• Missing required Redis configuration: {missing_var}. Provide
• similarity_threshold must be provided, passed None
• Invalid mode: {custom_auth_settings['mode']}

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