{"record":{"id":"edd7a2b8bbb16810","repo":"BerriAI/litellm","slug":"valkey-semantic-does-not-support-cluster-mode-enab","errorCode":null,"errorMessage":"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.","messagePattern":"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\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"litellm/caching/valkey_semantic_cache.py","lineNumber":70,"sourceCode":"        self,\n        host: str | None = None,\n        port: str | None = None,\n        password: str | None = None,\n        redis_url: str | None = None,\n        similarity_threshold: float | None = None,\n        embedding_model: str = \"text-embedding-ada-002\",\n        index_name: str | None = None,\n        ssl: bool = False,\n        startup_nodes: list | None = None,\n        sync_client: Redis | None = None,\n        async_client: AsyncRedis | None = None,\n        **kwargs: Any,\n    ):\n        if similarity_threshold is None:\n            raise ValueError(\"similarity_threshold must be provided, passed None\")\n\n        if startup_nodes:\n            raise ValueError(\n                \"valkey-semantic does not support cluster-mode-enabled (multi-shard) \"\n                \"endpoints. The async cluster client cannot route the FT.* search \"\n                \"commands reliably. Point it at a cluster-mode-disabled endpoint \"\n                \"instead (a primary with replicas is fine; only horizontal sharding \"\n                \"is unsupported), or pass a single redis_url. On AWS, vector search \"\n                \"needs ElastiCache for Valkey 8.2+ on a node-based cluster.\"\n            )\n\n        self.similarity_threshold = similarity_threshold\n        self.embedding_model = embedding_model\n        self.index_name = index_name or self.DEFAULT_VALKEY_INDEX_NAME\n        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)","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/BerriAI/litellm/blob/6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d/litellm/caching/valkey_semantic_cache.py#L52-L88","documentation":"The Valkey semantic cache only supports non-clustered endpoints. Passing startup_nodes (the multi-shard cluster topology) raises this ValueError by design: the async cluster client cannot reliably route valkey-search FT.* commands across shards, so LiteLLM refuses rather than silently corrupting search results. The message prescribes the supported alternatives, including ElastiCache for Valkey 8.2+ in node-based (non-sharded) mode.","triggerScenarios":"Passing startup_nodes=[{'host': ..., 'port': ...}, ...] to ValkeySemanticCache, i.e. pointing the semantic cache at a cluster-mode-enabled Valkey/Redis (multi-shard) deployment such as AWS ElastiCache cluster-mode-on or Redis Cluster.","commonSituations":"Teams reuse an existing sharded ElastiCache cluster for semantic caching; migrating from redis-semantic cache config that happened to include startup_nodes.","solutions":["Point the cache at a cluster-mode-disabled endpoint: pass a single redis_url (a primary with replicas is fine)","On AWS, use ElastiCache for Valkey 8.2+ on a node-based cluster (cluster mode off) for vector search","Remove startup_nodes from the cache config entirely and supply redis_url or host/port instead"],"exampleFix":"# before\ncache = ValkeySemanticCache(similarity_threshold=0.8,\n    startup_nodes=[{'host': 'shard1', 'port': 6379}, {'host': 'shard2', 'port': 6379}])\n\n# after\ncache = ValkeySemanticCache(similarity_threshold=0.8,\n    redis_url='rediss://:password@primary.node.cache.amazonaws.com:6379')","handlingStrategy":"validation","validationCode":"if cfg.get('startup_nodes'):\n    raise ValueError(\n        'valkey-semantic cache cannot use cluster-mode (multi-shard) endpoints; '\n        'point it at a cluster-mode-disabled endpoint via redis_url instead'\n    )","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Provision a dedicated non-sharded Valkey 8.2+ endpoint for vector search (on AWS: node-based ElastiCache cluster)","Never reuse sharded cluster connection settings for semantic caches"],"tags":["valkey","semantic-cache","cluster","elasticsearch-aws","configuration"],"backgroundTag":null,"analyzedSha":"6c2dcb801bf2b75c18f1bb24140e7cf57465cc4d","analyzedAt":"2026-08-15T07:12:03.035Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}