redis/redis-py · error · RedisError

Maintenance notifications are not supported with

Error message

Maintenance notifications are not supported with {connection_class}

What it means

Raised as RedisError by ConnectionPool.__init__ when maint_notifications_config.enabled is True but the chosen connection_class is UnixDomainSocketConnection or any class that is not a subclass of MaintNotificationsAbstractConnection. The default redis.connection.Connection supports maintenance notifications; UDS and arbitrary custom classes do not, so enabling the feature against them is rejected up front.

Solutions

Use the default Connection class (TCP) when you need maintenance notifications.
If you need UDS, set maint_notifications_config=MaintNotificationsConfig(enabled=False) or omit it.
Make your custom connection_class inherit from MaintNotificationsAbstractConnection if you need notifications with it.

Example fix

# before
pool = ConnectionPool(connection_class=UnixDomainSocketConnection,
                    maint_notifications_config=MaintNotificationsConfig(enabled=True))
# after
pool = ConnectionPool(connection_class=UnixDomainSocketConnection,
                    maint_notifications_config=MaintNotificationsConfig(enabled=False))

Defensive patterns

Strategy: validation

Validate before calling

from redis.connection import Connection, UnixDomainSocketConnection, MaintNotificationsAbstractConnection

def connection_supports_maint(connection_class) -> bool:
    try:
        return issubclass(connection_class, MaintNotificationsAbstractConnection)
    except TypeError:
        return False

if maint_enabled and not connection_supports_maint(connection_class):
    raise ValueError(f'{connection_class} does not support maintenance notifications')

pool = ConnectionPool(connection_class=connection_class, maint_notifications_config=cfg)

Type guard

from redis.connection import MaintNotificationsAbstractConnection

def supports_maint_notifications(connection_class) -> bool:
    try:
        return issubclass(connection_class, MaintNotificationsAbstractConnection)
    except TypeError:
        return False

Try / catch

from redis.exceptions import RedisError
try:
    pool = ConnectionPool(connection_class=connection_class, maint_notifications_config=cfg)
except RedisError:
    pool = ConnectionPool(connection_class=connection_class,
                          maint_notifications_config=MaintNotificationsConfig(enabled=False))

Prevention

Don't combine UDS (or custom non-maint classes) with maintenance notifications.
Check issubclass(connection_class, MaintNotificationsAbstractConnection) before enabling.
Default to enabled=False when using UDS.

When it happens

Trigger: Constructing ConnectionPool(connection_class=UnixDomainSocketConnection, maint_notifications_config=MaintNotificationsConfig(enabled=True)). Passing a custom connection_class that does not subclass MaintNotificationsAbstractConnection with notifications enabled.

Common situations: Combining UDS connectivity with maintenance-notification config. Globally enabling maintenance notifications while a code path uses a UDS pool. Third-party/custom connection class used with the default RESP3 auto-enable.

Related errors

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

Appendix: source

Thrown at redis/connection.py:3017

        self._cache_factory = cache_factory

        try:
            supports_maint_notifications = issubclass(
                connection_class, MaintNotificationsAbstractConnection
            )
            is_unix_domain_socket_connection = issubclass(
                connection_class, UnixDomainSocketConnection
            )
        except TypeError:
            supports_maint_notifications = False
            is_unix_domain_socket_connection = False

        if is_unix_domain_socket_connection or not supports_maint_notifications:
            if (
                maint_notifications_config
                and maint_notifications_config.enabled is True
            ):
                raise RedisError(
                    "Maintenance notifications are not supported with "
                    f"{connection_class}"
                )
            maint_notifications_config = MaintNotificationsConfig(enabled=False)

        self._event_dispatcher = self._connection_kwargs.get("event_dispatcher", None)
        if self._event_dispatcher is None:
            self._event_dispatcher = EventDispatcher()

        if connection_kwargs.get("cache_config") or connection_kwargs.get("cache"):
            if not check_protocol_version(self._connection_kwargs.get("protocol"), 3):
                raise RedisError("Client caching is only supported with RESP version 3")

            cache = self._connection_kwargs.get("cache")

            if cache is not None:
                if not isinstance(cache, CacheInterface):
                    raise ValueError("Cache must implement CacheInterface")

View on GitHub (pinned to 6a6b581b48)