{"record":{"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/6a6b581b48225afa0b76912d1028c6035baee932/redis/cluster.py#L808-L844","documentation":"Raised by RedisCluster.__init__ when 'retry' is present in kwargs. Retry behavior in cluster mode is managed at the cluster-client level (self.retry) because retries must coordinate with MOVED/ASK redirection and slot ownership; a per-connection retry object would conflict with that logic. Pass retry as the dedicated top-level constructor argument instead.","triggerScenarios":"RedisCluster(host=..., port=..., retry=my_retry) — here retry lands in kwargs rather than the named parameter slot. Typically happens when constructing kwargs as a dict and passing via **kwargs without filtering.","commonSituations":"Building a generic kwargs dict for both standalone and cluster clients; upgrading from standalone Redis(retry=...) to cluster without adjusting call style; passing retry inside connection_kwargs.","solutions":["Pass retry as the explicit named argument: RedisCluster(host=..., port=..., retry=my_retry).","If assembling kwargs dynamically, pop 'retry' out and pass it positionally/named.","Confirm cluster_error_retry_attempts (constructor param) is used to size the cluster-level retry instead of a per-connection Retry object."],"exampleFix":"// before\nkwargs = {'retry': Retry(backoff, 3), 'socket_timeout': 1}\nclient = RedisCluster(host='localhost', port=7000, **kwargs)  # RedisClusterException\n\n// after\nretry = kwargs.pop('retry')\nclient = RedisCluster(host='localhost', port=7000, retry=retry, **kwargs)","handlingStrategy":"validation","validationCode":"retry = kwargs.pop('retry', None)\nclient = RedisCluster(host='localhost', port=7000, retry=retry, **kwargs)","typeGuard":"def kwargs_have_no_retry(kwargs) -> bool:\n    return 'retry' not in kwargs","tryCatchPattern":"from redis.cluster import RedisClusterException\ntry:\n    client = RedisCluster(host='localhost', port=7000, **kwargs)\nexcept RedisClusterException as e:\n    if 'retry' in str(e):\n        retry = kwargs.pop('retry')\n        client = RedisCluster(host='localhost', port=7000, retry=retry, **kwargs)\n    else:\n        raise","preventionTips":["Pass retry as the named constructor argument for cluster clients, never inside kwargs.","Filter shared kwargs dicts for cluster-incompatible keys before construction.","Use cluster_error_retry_attempts to size cluster-level retry instead of a per-connection Retry."],"tags":["cluster","config","retry","api-misuse"],"backgroundTag":null,"analyzedSha":"6a6b581b48225afa0b76912d1028c6035baee932","analyzedAt":"2026-08-10T12:52:44.840Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}