redis/redis-py · error · RedisError

Maintenance notifications are not supported for connection c

Error message

Maintenance notifications are not supported for connection class {connection_class_name}

What it means

Raised as a RedisError when maintenance notifications are explicitly enabled but the configured connection_class does not inherit from AsyncMaintNotificationsAbstractConnection (checked by _maintenance_notifications_connection_class_supported via issubclass). Custom connection classes must adopt the mixin so handlers can safely update connection state on notification events.

Source

Thrown at redis/asyncio/connection.py:1926

        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.
                    raise RedisError(
                        "Maintenance notifications are not supported for connections "
                        "without a host"
                    )
                self._maint_notifications_pool_handler = None
                self._oss_cluster_maint_notifications_handler = None
                return

            if not is_protocol_supported:
                raise RedisError(
                    "Maintenance notifications handlers on connection are only supported with RESP version 3"
                )

View on GitHub (pinned to da03cdc7e8)

Solutions

  1. Make your custom connection class inherit AsyncMaintNotificationsAbstractConnection (and Connection).
  2. Disable maintenance notifications (enabled=False / omit the config) if you do not need them.
  3. Use the built-in Connection class, which already satisfies the check.

Example fix

// before
class MyConn(redis.asyncio.Connection): ...
r = redis.asyncio.Redis(connection_class=MyConn,
    maint_notifications_config=MaintNotificationsConfig(enabled=True))

// after
class MyConn(redis.asyncio.Connection, AsyncMaintNotificationsAbstractConnection): ...
r = redis.asyncio.Redis(connection_class=MyConn,
    maint_notifications_config=MaintNotificationsConfig(enabled=True))
Defensive patterns

Strategy: type-guard

Validate before calling

from redis.asyncio.connection import AsyncMaintNotificationsAbstractConnection
def connection_class_supports_maint(cls) -> bool:
    try:
        return issubclass(cls, AsyncMaintNotificationsAbstractConnection)
    except TypeError:
        return False

Type guard

def supports_maintenance_notifications(connection_class) -> bool:
    from redis.asyncio.connection import AsyncMaintNotificationsAbstractConnection
    try:
        return issubclass(connection_class, AsyncMaintNotificationsAbstractConnection)
    except TypeError:
        return False

Try / catch

from redis.exceptions import RedisError
try:
    pool = ConnectionPool(connection_class=MyConn, maint_notifications_config=cfg)
except RedisError as e:
    if "connection class" in str(e):
        pool = ConnectionPool(connection_class=MyConn)  # no maint notifications
    else:
        raise

Prevention

When it happens

Trigger: Passing connection_class=MyCustomConnection (which does not subclass AsyncMaintNotificationsAbstractConnection) together with maint_notifications_config enabled=True, or with an oss_cluster_maint_notifications_handler. The connection_class name is included in the message.

Common situations: Using a third-party/custom connection class that predates the maintenance-notifications API; wrapping the standard Connection for instrumentation without inheriting the mixin; enabling OSS-cluster maint notifications on a client whose pool uses a non-supported class.

Related errors

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