{"record":{"id":"1a8ce98011070c9d","repo":"redis/redis-py","slug":"unix-domain-socket-is-not-supported-in-cluster-mod","errorCode":null,"errorMessage":"Unix domain socket is not supported in cluster mode","messagePattern":"Unix domain socket is not supported in cluster mode","errorType":"exception","errorClass":"RedisClusterException","httpStatus":null,"severity":"error","filePath":"redis/asyncio/cluster.py","lineNumber":467,"sourceCode":"        ssl_certfile: str | None = None,\n        ssl_check_hostname: bool = True,\n        ssl_keyfile: str | None = None,\n        ssl_min_version: \"TLSVersion | None\" = None,\n        ssl_ciphers: str | None = None,\n        protocol: int | None = None,\n        legacy_responses: bool = True,\n        address_remap: Callable[[Tuple[str, int]], Tuple[str, int]] | None = None,\n        event_dispatcher: EventDispatcher | None = None,\n        policy_resolver: AsyncPolicyResolver = AsyncStaticPolicyResolver(),\n        maint_notifications_config: MaintNotificationsConfig | None = None,\n    ) -> None:\n        if db:\n            raise RedisClusterException(\n                \"Argument 'db' must be 0 or None in cluster mode\"\n            )\n\n        if path:\n            raise RedisClusterException(\n                \"Unix domain socket is not supported in cluster mode\"\n            )\n\n        if (not host or not port) and not startup_nodes:\n            raise RedisClusterException(\n                \"RedisCluster requires at least one node to discover the cluster.\\n\"\n                \"Please provide one of the following or use RedisCluster.from_url:\\n\"\n                '   - host and port: RedisCluster(host=\"localhost\", port=6379)\\n'\n                \"   - startup_nodes: RedisCluster(startup_nodes=[\"\n                'ClusterNode(\"localhost\", 6379), ClusterNode(\"localhost\", 6380)])'\n            )\n\n        computed_driver_info = resolve_driver_info(driver_info, lib_name, lib_version)\n\n        kwargs: Dict[str, Any] = {\n            \"max_connections\": max_connections,\n            \"connection_class\": Connection,\n            # Client related kwargs","sourceCodeStart":449,"sourceCodeEnd":485,"githubUrl":"https://github.com/redis/redis-py/blob/6a6b581b48225afa0b76912d1028c6035baee932/redis/asyncio/cluster.py#L449-L485","documentation":"Raised in RedisCluster.__init__ when path is truthy. Unix domain sockets are unsupported for cluster mode because slot routing, MOVED/ASK redirection, and topology discovery rely on TCP host:port endpoints reported by the cluster bus. Passing path= (the standalone Redis unix-socket argument) is rejected.","triggerScenarios":"RedisCluster(unix_socket_path='/var/run/redis/redis.sock') or RedisCluster(path='/var/run/redis/redis.sock'); or constructing from a config dict that always sets path for standalone clients.","commonSituations":"Sharing a connection-config builder across standalone and cluster code paths; local dev using a unix socket for standalone Redis then pointing the same builder at a cluster.","solutions":["Do not pass path/unix_socket_path to RedisCluster; use host and port (or startup_nodes).","Branch your config builder: cluster clients get host/port, standalone clients may get path.","If you need a unix socket, use the standalone Redis() client against a single node, not the cluster client."],"exampleFix":"// before\nclient = RedisCluster(path='/var/run/redis/redis.sock')\n// after\nclient = RedisCluster(host='localhost', port=7000)","handlingStrategy":"validation","validationCode":"assert not path, 'Unix domain sockets are not supported in cluster mode'\nclient = RedisCluster(host=..., port=...)","typeGuard":"def is_tcp_cluster_config(path: str | None, host: str | None, port: int | None) -> bool:\n    return not path and bool(host) and bool(port)","tryCatchPattern":"from redis.exceptions import RedisClusterException\ntry:\n    client = RedisCluster(path=path)\nexcept RedisClusterException as e:\n    if 'Unix domain socket' in str(e):\n        client = RedisCluster(host='localhost', port=7000)\n    else:\n        raise","preventionTips":["Do not share a unix-socket config with the cluster client.","Validate cluster config separately from standalone config."],"tags":["cluster","configuration","init","unix-socket"],"backgroundTag":null,"analyzedSha":"6a6b581b48225afa0b76912d1028c6035baee932","analyzedAt":"2026-08-10T12:52:44.840Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}