{"record":{"id":"a3a1aa8af92dcdd9","repo":"BerriAI/litellm","slug":"missing-required-valkey-configuration-provide-hos","errorCode":null,"errorMessage":"Missing required Valkey configuration. Provide host and port (or VALKEY_HOST/VALKEY_PORT), or pass redis_url.","messagePattern":"Missing required Valkey configuration\\. Provide host and port \\(or VALKEY_HOST/VALKEY_PORT\\), or pass redis_url\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/caching/valkey_semantic_cache.py","lineNumber":100,"sourceCode":"        self.key_prefix = f\"{self.index_name}:\"\n        self._index_dim: int | None = None\n\n        resolved_url = None\n        if sync_client is None or async_client is None:\n            resolved_url = redis_url or self._build_valkey_url(host, port, password, ssl)\n        self.sync_client = sync_client if sync_client is not None else Redis.from_url(resolved_url)\n        self.async_client = async_client if async_client is not None else AsyncRedis.from_url(resolved_url)\n\n        print_verbose(f\"Valkey semantic-cache initializing index - {self.index_name}\")\n\n    @staticmethod\n    def _build_valkey_url(host: str | None, port: str | None, password: str | None, ssl: bool = False) -> str:\n        host = host or os.environ.get(\"VALKEY_HOST\") or os.environ.get(\"REDIS_HOST\")\n        port = port or os.environ.get(\"VALKEY_PORT\") or os.environ.get(\"REDIS_PORT\")\n        password = password or os.environ.get(\"VALKEY_PASSWORD\") or os.environ.get(\"REDIS_PASSWORD\")\n\n        if not host or not port:\n            raise ValueError(\n                \"Missing required Valkey configuration. Provide host and port \"\n                \"(or VALKEY_HOST/VALKEY_PORT), or pass redis_url.\"\n            )\n\n        credentials: Final = f\":{password}@\" if password else \"\"\n        scheme: Final = \"rediss\" if ssl else \"redis\"\n        return f\"{scheme}://{credentials}{host}:{port}\"\n\n    @classmethod\n    def _scope_tag(cls, key: str) -> str:\n        # valkey-search TAG fields tokenize on punctuation and do not honour\n        # backslash escaping, so an arbitrary cache key cannot be matched\n        # verbatim. Hashing to hex yields a token that is always exact-match\n        # safe and still uniquely isolates a caller's scope.\n        return hashlib.sha256(str(key).encode(\"utf-8\")).hexdigest()\n\n    @staticmethod\n    def _embedding_to_bytes(embedding: list[float]) -> bytes:","sourceCodeStart":82,"sourceCodeEnd":118,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/caching/valkey_semantic_cache.py#L82-L118","documentation":"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.","triggerScenarios":"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`.","commonSituations":"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.","solutions":["Pass redis_url directly: ValkeySemanticCache(redis_url='redis://:pass@valkey:6379', similarity_threshold=0.8)","Or set VALKEY_HOST and VALKEY_PORT (or REDIS_HOST/REDIS_PORT) in the running process's environment","Verify with python -c \"import os; print(os.environ.get('VALKEY_HOST'), os.environ.get('VALKEY_PORT'))\""],"exampleFix":"# before\ncache = ValkeySemanticCache(similarity_threshold=0.8)  # no url, no env vars\n\n# after\ncache = ValkeySemanticCache(similarity_threshold=0.8,\n                           redis_url='redis://:mypassword@valkey.internal:6379')","handlingStrategy":"validation","validationCode":"import os\n\nhost = cfg.get('host') or os.environ.get('VALKEY_HOST') or os.environ.get('REDIS_HOST')\nport = cfg.get('port') or os.environ.get('VALKEY_PORT') or os.environ.get('REDIS_PORT')\nif not (cfg.get('redis_url') or (host and port)):\n    raise ValueError('Provide redis_url or set VALKEY_HOST/VALKEY_PORT for valkey semantic caching')","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Prefer redis_url over scattered host/port env vars","Add VALKEY_HOST/VALKEY_PORT to deployment env templates alongside REDIS_*"],"tags":["valkey","semantic-cache","environment","configuration"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}