BerriAI/litellm · error · ValueError

Missing required Valkey configuration. Provide host and port

Error message

Missing required Valkey configuration. Provide host and port (or VALKEY_HOST/VALKEY_PORT), or pass redis_url.

What it means

If redis_url is not supplied, ValkeySemanticCache._build_valkey_url resolves host and port from arguments, then the VALKEY_HOST/VALKEY_PORT environment variables (falling back to REDIS_HOST/REDIS_PORT). Missing host or port raises this ValueError. Password is optional; host and port are not.

Source

Thrown at litellm/caching/valkey_semantic_cache.py:100

        self.key_prefix = f"{self.index_name}:"
        self._index_dim: int | None = None

        resolved_url = None
        if sync_client is None or async_client is None:
            resolved_url = redis_url or self._build_valkey_url(host, port, password, ssl)
        self.sync_client = sync_client if sync_client is not None else Redis.from_url(resolved_url)
        self.async_client = async_client if async_client is not None else AsyncRedis.from_url(resolved_url)

        print_verbose(f"Valkey semantic-cache initializing index - {self.index_name}")

    @staticmethod
    def _build_valkey_url(host: str | None, port: str | None, password: str | None, ssl: bool = False) -> str:
        host = host or os.environ.get("VALKEY_HOST") or os.environ.get("REDIS_HOST")
        port = port or os.environ.get("VALKEY_PORT") or os.environ.get("REDIS_PORT")
        password = password or os.environ.get("VALKEY_PASSWORD") or os.environ.get("REDIS_PASSWORD")

        if not host or not port:
            raise ValueError(
                "Missing required Valkey configuration. Provide host and port "
                "(or VALKEY_HOST/VALKEY_PORT), or pass redis_url."
            )

        credentials: Final = f":{password}@" if password else ""
        scheme: Final = "rediss" if ssl else "redis"
        return f"{scheme}://{credentials}{host}:{port}"

    @classmethod
    def _scope_tag(cls, key: str) -> str:
        # valkey-search TAG fields tokenize on punctuation and do not honour
        # backslash escaping, so an arbitrary cache key cannot be matched
        # verbatim. Hashing to hex yields a token that is always exact-match
        # safe and still uniquely isolates a caller's scope.
        return hashlib.sha256(str(key).encode("utf-8")).hexdigest()

    @staticmethod
    def _embedding_to_bytes(embedding: list[float]) -> bytes:

View on GitHub (pinned to 6c2dcb801b)

Solutions

  1. Pass redis_url directly: ValkeySemanticCache(redis_url='redis://:pass@valkey:6379', similarity_threshold=0.8)
  2. Or set VALKEY_HOST and VALKEY_PORT (or REDIS_HOST/REDIS_PORT) in the running process's environment
  3. Verify with python -c "import os; print(os.environ.get('VALKEY_HOST'), os.environ.get('VALKEY_PORT'))"

Example fix

# before
cache = ValkeySemanticCache(similarity_threshold=0.8)  # no url, no env vars

# after
cache = ValkeySemanticCache(similarity_threshold=0.8,
                           redis_url='redis://:mypassword@valkey.internal:6379')
Defensive patterns

Strategy: validation

Validate before calling

import os

host = cfg.get('host') or os.environ.get('VALKEY_HOST') or os.environ.get('REDIS_HOST')
port = cfg.get('port') or os.environ.get('VALKEY_PORT') or os.environ.get('REDIS_PORT')
if not (cfg.get('redis_url') or (host and port)):
    raise ValueError('Provide redis_url or set VALKEY_HOST/VALKEY_PORT for valkey semantic caching')

Prevention

When it happens

Trigger: Constructing the cache with neither redis_url nor host+port, where VALKEY_HOST/VALKEY_PORT (and REDIS_HOST/REDIS_PORT) are unset. Only the first missing piece is needed to trigger — the guard checks `if not host or not port`.

Common situations: Assuming Valkey cache reuses REDIS_* env vars that exist on a different host; setting VALKEY_ENDPOINT instead of VALKEY_HOST; env vars not injected into the container.

Related errors

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