BerriAI/litellm · error · ValueError

Missing required Redis configuration: {missing_var}. Provide

Error message

Missing required Redis configuration: {missing_var}. Provide {missing_var} or redis_url.

What it means

When no redis_url is given, the Redis semantic cache builds one from host/port/password, falling back to the REDIS_HOST, REDIS_PORT and REDIS_PASSWORD environment variables. If any one of them is missing from both kwargs and the environment, the KeyError is caught and re-raised as a ValueError naming the first missing variable. This is purely a configuration-resolution failure at construction time.

Source

Thrown at litellm/caching/redis_semantic_cache.py:100

        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:
                # Raise a more informative exception if any of the required keys are missing
                missing_var: Final = e.args[0]
                raise ValueError(
                    f"Missing required Redis configuration: {missing_var}. Provide {missing_var} or redis_url."
                ) from e

            redis_url = f"redis://:{password}@{host}:{port}"

        print_verbose(f"Redis semantic-cache redis_url: {redis_url}")

        # Defer redisvl index construction until first use. redisvl's
        # CustomTextVectorizer eagerly embeds a probe string at construction;
        # building lazily ensures that probe runs after llm_router is wired so
        # per-deployment auth (e.g. Bedrock aws_role_name) is applied.
        self._index_name = index_name
        self._redis_url = redis_url
        self._llmcache = None

    @property
    def llmcache(self) -> object:
        if getattr(self, "_llmcache", None) is None:

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Simplest: pass redis_url directly, e.g. RedisSemanticCache(redis_url='redis://:password@host:6379', similarity_threshold=0.8)
2. Or export all three variables: REDIS_HOST, REDIS_PORT, REDIS_PASSWORD (set REDIS_PASSWORD='' only if explicitly provided — the code requires the key to exist)
3. Check the variable named in the error message and add it to the deployment environment (Docker env, k8s secret, .env actually loaded)

Example fix

# before
os.environ['REDIS_HOST'] = 'localhost'  # PORT, PASSWORD missing
cache = RedisSemanticCache(similarity_threshold=0.8)

# after
cache = RedisSemanticCache(similarity_threshold=0.8,
                           redis_url='redis://:mypassword@localhost:6379')

import os

def resolve_redis_url(cfg: dict) -> str:
    if cfg.get('redis_url'):
        return cfg['redis_url']
    missing = [v for v in ('REDIS_HOST', 'REDIS_PORT', 'REDIS_PASSWORD') if not os.environ.get(v)]
    if missing or not (cfg.get('host') and cfg.get('port')):
        raise ValueError(f'Provide redis_url, or host/port/password args, or set {missing}')
    return f"redis://:{cfg.get('password') or os.environ['REDIS_PASSWORD']}@{cfg.get('host') or os.environ['REDIS_HOST']}:{cfg.get('port') or os.environ['REDIS_PORT']}"

When it happens

Trigger: Constructing RedisSemanticCache with neither redis_url nor complete host+port+password, where at least one of REDIS_HOST/REDIS_PORT/REDIS_PASSWORD is unset in the environment. The message tells you exactly which variable was missing first.

Common situations: REDIS_PASSWORD unset on a passwordless local Redis (the code still requires the env var); env vars present in dev shell but absent in the container/systemd unit; typo like REDIS_ENDPOINT instead of REDIS_HOST.

Related errors

• Qdrant url must be provided
• similarity_threshold must be provided, passed None
• Missing required Valkey configuration. Provide host and port
• collection_name must be provided, passed None
• similarity_threshold must be provided, passed None

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