redis/redis-py · error · RedisError

Maintenance notifications are not supported for Unix domain

Error message

Maintenance notifications are not supported for Unix domain socket connections

What it means

Raised as a RedisError during connection-pool initialization when maintenance notifications are explicitly enabled but the connection uses a Unix domain socket ('path' in connection_kwargs). CLIENT MAINT_NOTIFICATIONS needs a host:port endpoint to describe, so UDS connections are unsupported. Only fires when maint_notifications_config.enabled is True (explicit opt-in).

Source

Thrown at redis/asyncio/connection.py:1914

    ) -> None:
        protocol = kwargs.get("protocol")
        is_protocol_supported = check_protocol_version(protocol, 3)
        is_connection_supported = self._maintenance_notifications_supported()

        if (
            maint_notifications_config is None
            and is_protocol_supported
            and is_connection_supported
        ):
            maint_notifications_config = MaintNotificationsConfig()

        if maint_notifications_config and maint_notifications_config.enabled:
            if not is_connection_supported:
                if maint_notifications_config.enabled is True:
                    # Unix sockets do not have a host endpoint for CLIENT
                    # MAINT_NOTIFICATIONS to describe.
                    if "path" in self.connection_kwargs:
                        raise RedisError(
                            "Maintenance notifications are not supported for "
                            "Unix domain socket connections"
                        )

                    # Custom connection classes must inherit the async maintenance
                    # mixin so handlers can update connection state safely.
                    if not self._maintenance_notifications_connection_class_supported():
                        connection_class = getattr(self, "connection_class", None)
                        connection_class_name = getattr(
                            connection_class, "__name__", connection_class
                        )
                        raise RedisError(
                            "Maintenance notifications are not supported for "
                            f"connection class {connection_class_name}"
                        )

                    # TCP-like connections still need a host to identify the
                    # endpoint that can move during maintenance.

View on GitHub (pinned to da03cdc7e8)

Solutions

Disable maintenance notifications for UDS clients: omit maint_notifications_config or set enabled=False (the default).
Switch the connection to a TCP (host:port) endpoint if you genuinely need maintenance notifications.
Do not pass an oss_cluster_maint_notifications_handler when using unix://.

Example fix

// before
r = redis.asyncio.Redis(unix_socket_path="/var/run/redis/redis.sock",
    maint_notifications_config=MaintNotificationsConfig(enabled=True))

// after
r = redis.asyncio.Redis(unix_socket_path="/var/run/redis/redis.sock")

Defensive patterns

Strategy: validation

Validate before calling

def maint_notifications_compatible(connection_kwargs: dict) -> bool:
    return "path" not in connection_kwargs  # UDS unsupported

Try / catch

from redis.exceptions import RedisError
try:
    r = redis.asyncio.Redis(unix_socket_path=p, maint_notifications_config=cfg)
except RedisError as e:
    if "Unix domain socket" in str(e):
        r = redis.asyncio.Redis(unix_socket_path=p)  # drop maint notifications
    else:
        raise

Prevention

Don't enable maintenance notifications on UDS clients.
Let the library auto-disable the feature rather than forcing enabled=True.
Use TCP if you need maintenance notifications.

When it happens

Trigger: Constructing a pool/client with connection_class=UnixDomainSocketConnection (or unix:// URL) together with maint_notifications_config=MaintNotificationsConfig(enabled=True) or an oss_cluster_maint_notifications_handler. The check at line 1913 detects 'path' in connection_kwargs.

Common situations: Enabling the maintenance-notifications feature against a UDS deployment; copying a cluster config (which sets up OSS maint notifications) onto a unix-socket client; explicitly enabling the feature when auto-detection would otherwise silently disable it.

Related errors

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