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 RedisError from the async maintenance-notifications pool mixin when maintenance notifications are explicitly enabled (config.enabled is True) but the connection is a Unix domain socket ('path' in connection_kwargs). UDS connections have no host endpoint to describe in CLIENT MAINT_NOTIFICATIONS, so the feature is unsupported. The check fires during pool construction, before any connect.

Solutions

Disable maintenance notifications for UDS deployments: pass maint_notifications_config=None or MaintNotificationsConfig(enabled=False).
Switch the UDS connection to a TCP connection if you need maintenance notifications.
Make the factory conditionally enable the feature only when connection_class is TCP/SSL.

Example fix

// before
pool = ConnectionPool.from_url('unix:///var/run/redis.sock', maint_notifications_config=MaintNotificationsConfig(enabled=True))
// after
pool = ConnectionPool.from_url('unix:///var/run/redis.sock', maint_notifications_config=None)

Defensive patterns

Strategy: validation

Validate before calling

def maint_config_for_uds(enabled: bool | None):
    # UDS does not support maintenance notifications
    return None if enabled else None

Type guard

from redis.exceptions import RedisError

def is_uds_maint_error(exc: BaseException) -> bool:
    return isinstance(exc, RedisError) and 'Unix domain socket' in str(exc)

Try / catch

from redis.exceptions import RedisError

try:
    pool = ConnectionPool.from_url('unix:///var/run/redis.sock', maint_notifications_config=cfg)
except RedisError as e:
    if 'Unix domain socket' in str(e):
        pool = ConnectionPool.from_url('unix:///var/run/redis.sock')  # no maint
    else:
        raise

Prevention

Do not enable maintenance notifications on UDS pools.
Make config factories conditional on connection_class.
Document that maintenance notifications require TCP/SSL endpoints.

When it happens

Trigger: Constructing an async client/pool from a unix:// URL with maint_notifications_config=MaintNotificationsConfig(enabled=True) (or a config object whose enabled is explicitly True). TCP/SSL paths take a different branch.

Common situations: Reusing a maintenance-notifications-enabled pool config across both TCP and UDS deployments; enabling the feature globally in a shared factory; testing locally over UDS with a config meant for production TCP.

Related errors

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

Appendix: source

Thrown at redis/asyncio/connection.py:1917

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