redis/redis-py · error · RedisClusterException

RedisCluster does not currently support Unix Domain Socket c

Error message

RedisCluster does not currently support Unix Domain Socket connections

What it means

Raised in `RedisCluster.__init__` when the URL passed to the constructor contains a `path` component, indicating a Unix Domain Socket address. The cluster client does not implement UDS-based node topology/discovery, so a UDS URL is rejected upfront with RedisClusterException rather than failing opaquely later.

Source

Thrown at redis/cluster.py:836

                "Argument 'db' is not possible to use in cluster mode"
            )

        if "retry" in kwargs:
            # Argument 'retry' is not possible to be used in kwargs when in cluster mode
            # the kwargs are set to the lower level connections to the cluster nodes
            # and there we provide retry configuration without retries allowed.
            # The retries should be handled on cluster client level.
            raise RedisClusterException(
                "The 'retry' argument cannot be used in kwargs when running in cluster mode."
            )

        # Get the startup node/s
        from_url = False
        if url is not None:
            from_url = True
            url_options = parse_url(url)
            if "path" in url_options:
                raise RedisClusterException(
                    "RedisCluster does not currently support Unix Domain "
                    "Socket connections"
                )
            if "db" in url_options and url_options["db"] != 0:
                # Argument 'db' is not possible to use in cluster mode
                raise RedisClusterException(
                    "A ``db`` querystring option can only be 0 in cluster mode"
                )
            kwargs.update(url_options)
            host = kwargs.get("host")
            port = kwargs.get("port", port)
            startup_nodes.append(ClusterNode(host, port))
        elif host is not None and port is not None:
            startup_nodes.append(ClusterNode(host, port))
        elif len(startup_nodes) == 0:
            # No startup node was provided
            raise RedisClusterException(
                "RedisCluster requires at least one node to discover the "

View on GitHub (pinned to da03cdc7e8)

Solutions

Use a TCP URL/host for RedisCluster: `RedisCluster(host='localhost', port=7000)`.
If you only need a single local Redis over UDS, use the standalone `redis.Redis.from_url('unix://...')` instead of RedisCluster.
Run a real cluster topology (3+ nodes) reachable over TCP.

Example fix

# before
rc = RedisCluster.from_url('unix:///var/run/redis/redis.sock')  # raises

# after
rc = redis.Redis.from_url('unix:///var/run/redis/redis.sock')  # standalone

Defensive patterns

Strategy: validation

Validate before calling

from urllib.parse import urlparse
u = urlparse(url)
if u.scheme.startswith('unix') or u.path:
    raise ValueError('RedisCluster does not support Unix Domain Sockets; use TCP')

Type guard

def is_tcp_url(url: str) -> bool:
    return url.startswith('redis://') or url.startswith('rediss://')

Prevention

Use TCP addresses for RedisCluster.
Use standalone redis.Redis for UDS connections.

When it happens

Trigger: Calling `RedisCluster.from_url('unix:///path/to/redis.sock')` or `RedisCluster(url='unix://...')`. The URL parser populates `url_options['path']` and the constructor raises.

Common situations: Reusing a standalone Redis UDS connection string for a cluster deployment; local dev with Redis-over-UDS attempting to add clustering.

Related errors

AI-assisted analysis of redis/redis-py@da03cdc7e8 (2026-08-04). Data as JSON: /data/errors/ad5c265632ad8510.json. Report an issue: GitHub.