redis/redis-py · error · RedisError

Maintenance notifications are not supported for connection…

Error message

Maintenance notifications are not supported for connection class {connection_class_name}

What it means

Raised as RedisError from the maintenance-notifications pool mixin when maintenance notifications are explicitly enabled but the connection class does not satisfy _maintenance_notifications_connection_class_supported(). Custom connection classes must inherit the async maintenance mixin so handlers can mutate connection state safely; otherwise the feature is refused at pool construction.

Solutions

Have your custom connection class inherit the async maintenance-notifications mixin (or whatever the project's supported base requires).
Disable maintenance notifications when using the custom class: maint_notifications_config=None.
Fall back to the stock connection class if maintenance notifications are more important than the customization.

Example fix

// before
pool = ConnectionPool(connection_class=MyConn, maint_notifications_config=MaintNotificationsConfig(enabled=True))
// after
class MyConn(MaintNotificationsMixin, SSLConnection): ...
pool = ConnectionPool(connection_class=MyConn, maint_notifications_config=MaintNotificationsConfig(enabled=True))

Defensive patterns

Strategy: validation

Validate before calling

def connection_class_supports_maint(connection_class: type) -> bool:
    # Custom classes must inherit the async maintenance mixin
    from redis.asyncio.connection import AbstractConnection
    maint_mixin_attrs = {'activate_maint_notifications_handling_if_enabled'}
    return any(hasattr(b, attr) for b in connection_class.__mro__ for attr in maint_mixin_attrs)

Type guard

from redis.exceptions import RedisError

def is_unsupported_class_error(exc: BaseException) -> bool:
    return isinstance(exc, RedisError) and 'connection class' in str(exc).lower() and 'Maintenance' in str(exc)

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)  # drop maint
    else:
        raise

Prevention

Inherit the maintenance mixin in custom connection classes that need the feature.
Disable maintenance notifications when using an unsupported custom class.
Run an integration test that constructs the pool with the real custom class.

When it happens

Trigger: Passing connection_class=MyCustomConnection (not derived from the supported async maintenance mixin) together with maint_notifications_config.enabled=True. Stock SSLConnection and TCP Connection are supported; arbitrary subclasses are not unless they opt in.

Common situations: Custom connection subclass for instrumentation/proxying that was not updated to inherit the maintenance mixin; feature flag rolled out to a code path that uses a bespoke connection class.

Related errors

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

Appendix: source

Thrown at redis/asyncio/connection.py:1929

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