{"record":{"id":"ad5c265632ad8510","repo":"redis/redis-py","slug":"rediscluster-does-not-currently-support-unix-domai","errorCode":null,"errorMessage":"RedisCluster does not currently support Unix Domain Socket connections","messagePattern":"RedisCluster does not currently support Unix Domain Socket connections","errorType":"exception","errorClass":"RedisClusterException","httpStatus":null,"severity":"error","filePath":"redis/cluster.py","lineNumber":836,"sourceCode":"                \"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                )\n            kwargs.update(url_options)\n            host = kwargs.get(\"host\")\n            port = kwargs.get(\"port\", port)\n            startup_nodes.append(ClusterNode(host, port))\n        elif host is not None and port is not None:\n            startup_nodes.append(ClusterNode(host, port))\n        elif len(startup_nodes) == 0:\n            # No startup node was provided\n            raise RedisClusterException(\n                \"RedisCluster requires at least one node to discover the \"","sourceCodeStart":818,"sourceCodeEnd":854,"githubUrl":"https://github.com/redis/redis-py/blob/6a6b581b48225afa0b76912d1028c6035baee932/redis/cluster.py#L818-L854","documentation":"Raised by RedisCluster.from_url (via __init__) when the parsed URL contains a 'path' component — i.e. a Unix Domain Socket URL (unix:///path/to/redis.sock). RedisCluster routes commands across multiple TCP nodes discovered via CLUSTER NODES, and the implementation does not support UDS endpoints for startup/discovery.","triggerScenarios":"RedisCluster.from_url('unix:///var/run/redis/redis.sock') or any URL whose parse_url yields a 'path' key. The guard at cluster.py:835 fires.","commonSituations":"Sharing a connection-URL config between standalone (which supports UDS) and cluster clients; local-dev setups that socket-connect to a single node and then try to use the cluster client.","solutions":["Use a TCP URL for RedisCluster: RedisCluster.from_url('redis://host:port').","If you must use UDS for a local single-node, use the standalone redis.Redis.from_url('unix://...') instead — but note a real cluster cannot be driven over UDS by this client.","Separate socket-based config from cluster config in your environment."],"exampleFix":"// before\nclient = RedisCluster.from_url('unix:///var/run/redis/redis.sock')  # RedisClusterException\n\n// after\nclient = RedisCluster.from_url('redis://localhost:7000')","handlingStrategy":"validation","validationCode":"from urllib.parse import urlparse\np = urlparse(url)\nif p.scheme.startswith('unix') or (p.path and not p.hostname):\n    raise ValueError('RedisCluster does not support Unix sockets; use a tcp redis:// URL')\nclient = RedisCluster.from_url(url)","typeGuard":"def url_is_tcp(url: str) -> bool:\n    return url.startswith('redis://') or url.startswith('rediss://')","tryCatchPattern":"from redis.cluster import RedisClusterException\ntry:\n    client = RedisCluster.from_url(url)\nexcept RedisClusterException as e:\n    if 'Unix Domain Socket' in str(e):\n        client = RedisCluster(host='localhost', port=7000)\n    else:\n        raise","preventionTips":["Use redis:// or rediss:// TCP URLs for cluster clients.","Keep UDS config exclusive to standalone redis.Redis.","Validate the URL scheme in config-loading code."],"tags":["cluster","config","unix-socket","url"],"backgroundTag":null,"analyzedSha":"6a6b581b48225afa0b76912d1028c6035baee932","analyzedAt":"2026-08-10T12:52:44.840Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}