redis/redis-py · error · RedisClusterException

Unix domain socket is not supported in cluster mode

Error message

Unix domain socket is not supported in cluster mode

What it means

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.

Solutions

  1. Do not pass path/unix_socket_path to RedisCluster; use host and port (or startup_nodes).
  2. Branch your config builder: cluster clients get host/port, standalone clients may get path.
  3. If you need a unix socket, use the standalone Redis() client against a single node, not the cluster client.

Example fix

// before
client = RedisCluster(path='/var/run/redis/redis.sock')
// after
client = RedisCluster(host='localhost', port=7000)
Defensive patterns

Strategy: validation

Validate before calling

assert not path, 'Unix domain sockets are not supported in cluster mode'
client = RedisCluster(host=..., port=...)

Type guard

def is_tcp_cluster_config(path: str | None, host: str | None, port: int | None) -> bool:
    return not path and bool(host) and bool(port)

Try / catch

from redis.exceptions import RedisClusterException
try:
    client = RedisCluster(path=path)
except RedisClusterException as e:
    if 'Unix domain socket' in str(e):
        client = RedisCluster(host='localhost', port=7000)
    else:
        raise

Prevention

When it happens

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

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

Related errors

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

Appendix: source

Thrown at redis/asyncio/cluster.py:467

        ssl_certfile: str | None = None,
        ssl_check_hostname: bool = True,
        ssl_keyfile: str | None = None,
        ssl_min_version: "TLSVersion | None" = None,
        ssl_ciphers: str | None = None,
        protocol: int | None = None,
        legacy_responses: bool = True,
        address_remap: Callable[[Tuple[str, int]], Tuple[str, int]] | None = None,
        event_dispatcher: EventDispatcher | None = None,
        policy_resolver: AsyncPolicyResolver = AsyncStaticPolicyResolver(),
        maint_notifications_config: MaintNotificationsConfig | None = None,
    ) -> None:
        if db:
            raise RedisClusterException(
                "Argument 'db' must be 0 or None in cluster mode"
            )

        if path:
            raise RedisClusterException(
                "Unix domain socket is not supported in cluster mode"
            )

        if (not host or not port) and not startup_nodes:
            raise RedisClusterException(
                "RedisCluster requires at least one node to discover the cluster.\n"
                "Please provide one of the following or use RedisCluster.from_url:\n"
                '   - host and port: RedisCluster(host="localhost", port=6379)\n'
                "   - startup_nodes: RedisCluster(startup_nodes=["
                'ClusterNode("localhost", 6379), ClusterNode("localhost", 6380)])'
            )

        computed_driver_info = resolve_driver_info(driver_info, lib_name, lib_version)

        kwargs: Dict[str, Any] = {
            "max_connections": max_connections,
            "connection_class": Connection,
            # Client related kwargs

View on GitHub (pinned to 6a6b581b48)