{"id":"c2fef4c59b65be49","repo":"redis/redis-py","slug":"the-retry-argument-cannot-be-used-in-kwargs-when","errorCode":null,"errorMessage":"The 'retry' argument cannot be used in kwargs when running in cluster mode.","messagePattern":"The 'retry' argument cannot be used in kwargs when running in cluster mode\\.","errorType":"exception","errorClass":"RedisClusterException","httpStatus":null,"severity":"error","filePath":"redis/cluster.py","lineNumber":826,"sourceCode":"            RedisClusterException:\n                - db (Redis do not support database SELECT in cluster mode)\n\n        \"\"\"\n        if startup_nodes is None:\n            startup_nodes = []\n\n        if \"db\" in kwargs:\n            # Argument 'db' is not possible to use in cluster mode\n            raise RedisClusterException(\n                \"Argument 'db' is not possible to use in cluster mode\"\n            )\n\n        if \"retry\" in kwargs:\n            # Argument 'retry' is not possible to be used in kwargs when in cluster mode\n            # the kwargs are set to the lower level connections to the cluster nodes\n            # and there we provide retry configuration without retries allowed.\n            # The retries should be handled on cluster client level.\n            raise RedisClusterException(\n                \"The 'retry' argument cannot be used in kwargs when running in cluster mode.\"\n            )\n\n        # Get the startup node/s\n        from_url = False\n        if url is not None:\n            from_url = True\n            url_options = parse_url(url)\n            if \"path\" in url_options:\n                raise RedisClusterException(\n                    \"RedisCluster does not currently support Unix Domain \"\n                    \"Socket connections\"\n                )\n            if \"db\" in url_options and url_options[\"db\"] != 0:\n                # Argument 'db' is not possible to use in cluster mode\n                raise RedisClusterException(\n                    \"A ``db`` querystring option can only be 0 in cluster mode\"\n                )","sourceCodeStart":808,"sourceCodeEnd":844,"githubUrl":"https://github.com/redis/redis-py/blob/da03cdc7e8731092b13e395605c3c1fb2de25de1/redis/cluster.py#L808-L844","documentation":"Raised in `RedisCluster.__init__` when `'retry'` is present in kwargs. The retry configuration for the cluster client must be supplied via the dedicated top-level `retry` constructor parameter (it is applied at the cluster-routing layer, not per-node), so passing retry inside connection kwargs is rejected to avoid it being silently applied to individual node connections without the cluster-level orchestration.","triggerScenarios":"Calling `RedisCluster(..., retry=Retry(...))` where `retry` is mistakenly placed in a kwargs/connection_kwargs dict instead of as the constructor's explicit `retry` parameter; spreading a generic Redis client config into RedisCluster.","commonSituations":"Sharing config dicts between standalone Redis() and RedisCluster(); migrating retry settings and accidentally passing them as connection kwargs.","solutions":["Pass retry as the explicit constructor argument: `RedisCluster(host=..., port=..., retry=Retry(backoff, retries))`.","When sharing a config dict, pop `retry` out for cluster clients: `retry = kwargs.pop('retry', None)`.","Check that the kwarg name is not shadowed by a helper that bundles everything into **kwargs."],"exampleFix":"# before\nkwargs = {'retry': Retry(NoBackoff(), 3)}\nrc = RedisCluster(host='h', port=7000, **kwargs)  # raises\n\n# after\nrc = RedisCluster(host='h', port=7000, retry=Retry(NoBackoff(), 3))","handlingStrategy":"validation","validationCode":"retry = kwargs.pop('retry', None)  # never pass retry inside kwargs\nrc = RedisCluster(host='h', port=7000, retry=retry, **kwargs)","typeGuard":"def cluster_kwargs_ok(kwargs: dict) -> bool:\n    return 'retry' not in kwargs","tryCatchPattern":null,"preventionTips":["Pass retry as the explicit RedisCluster(retry=...) parameter.","Do not bundle retry into shared connection-kwargs dicts."],"tags":["cluster","config","retry","initialization"],"analyzedSha":"da03cdc7e8731092b13e395605c3c1fb2de25de1","analyzedAt":"2026-08-04T20:26:47.563Z","schemaVersion":2}