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 by RedisCluster.__init__ (redis/asyncio/cluster.py:466) when a `path` (Unix domain socket) argument is provided. Cluster routing relies on host:port endpoints discovered via CLUSTER NODES/SLOTS, and UDS endpoints do not fit that discovery model, so the async cluster client rejects them at construction with RedisClusterException.

Source

Thrown at redis/asyncio/cluster.py:466

        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 da03cdc7e8)

Solutions

Connect over TCP (host + port) for cluster mode.
If a UDS front-end exists, put it behind a TCP proxy/sidecar and point the cluster client at the TCP endpoint.
Use the standalone redis.asyncio.Redis (not RedisCluster) for single-node UDS access.

Example fix

// before
c = RedisCluster(path='/var/run/redis/redis.sock')
// after
c = RedisCluster(host='localhost', port=16379)

Defensive patterns

Strategy: validation

Validate before calling

if path:
    raise ValueError('RedisCluster does not support Unix domain sockets; use TCP')
c = RedisCluster(host=host, port=port)

Prevention

Use TCP host:port for cluster connections.
If a UDS is mandatory, front it with a TCP proxy.
Use redis.asyncio.Redis for single-node UDS access.

When it happens

Trigger: Constructing RedisCluster(path='/var/run/redis/redis.sock', ...). The `if path:` guard fires right after the db check.

Common situations: Porting a standalone client that connected over a Unix socket to a cluster topology; local-dev setups that prefer UDS for performance.

Related errors

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