redis/redis-py · error · RedisClusterException

RedisCluster does not currently support Unix Domain Socket…

Error message

RedisCluster does not currently support Unix Domain Socket connections

What it means

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.

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.

Example fix

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

// after
client = RedisCluster.from_url('redis://localhost:7000')

Defensive patterns

Strategy: validation

Validate before calling

from urllib.parse import urlparse
p = urlparse(url)
if p.scheme.startswith('unix') or (p.path and not p.hostname):
    raise ValueError('RedisCluster does not support Unix sockets; use a tcp redis:// URL')
client = RedisCluster.from_url(url)

Type guard

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

Try / catch

from redis.cluster import RedisClusterException
try:
    client = RedisCluster.from_url(url)
except RedisClusterException as e:
    if 'Unix Domain Socket' in str(e):
        client = RedisCluster(host='localhost', port=7000)
    else:
        raise

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of redis/redis-py@6a6b581b48 (2026-08-10). Data as JSON: /api/errors/ad5c265632ad8510. Report an issue: GitHub.

Appendix: 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 6a6b581b48)