redis/redis-py · error · RedisError

Maintenance notifications are not supported with {connection

Error message

Maintenance notifications are not supported with {connection_class}

What it means

Raised as a RedisError by ConnectionPool.__init__ (connection.py:2997-3005) when maint_notifications_config.enabled is True but the connection_class is UnixDomainSocketConnection or a class that does not subclass MaintNotificationsAbstractConnection (checked via issubclass at lines 2987-2995). Maintenance notifications require a connection class that implements the notification-handling protocol.

Source

Thrown at redis/connection.py:3002

        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 da03cdc7e8)

Solutions

1. Disable maintenance notifications for Unix-socket or unsupported connection classes: pass MaintNotificationsConfig(enabled=False) (the constructor does this automatically when the class is unsupported and config is not explicitly enabled).
2. Use a TCP Connection (the default) if maintenance notifications are required.
3. If using a custom connection_class, ensure it subclasses MaintNotificationsAbstractConnection before enabling notifications.

Example fix

# before
from redis.maint_notifications import MaintNotificationsConfig
pool = redis.ConnectionPool(
    connection_class=redis.UnixDomainSocketConnection,
    path="/var/run/redis/redis.sock",
    maint_notifications_config=MaintNotificationsConfig(enabled=True))

# after (disable notifications for UDS)
pool = redis.ConnectionPool(
    connection_class=redis.UnixDomainSocketConnection,
    path="/var/run/redis/redis.sock",
    maint_notifications_config=MaintNotificationsConfig(enabled=False))

from redis.connection import UnixDomainSocketConnection
from redis.maint_notifications import MaintNotificationsConfig

def safe_pool(connection_class, enabled, **kw):
    if enabled and connection_class in (UnixDomainSocketConnection,):
        enabled = False
    cfg = MaintNotificationsConfig(enabled=enabled)
    return redis.ConnectionPool(connection_class=connection_class, maint_notifications_config=cfg, **kw)

from redis.connection import MaintNotificationsAbstractConnection, UnixDomainSocketConnection
def supports_maint_notifications(connection_class) -> bool:
    try:
        return (issubclass(connection_class, MaintNotificationsAbstractConnection)
                and not issubclass(connection_class, UnixDomainSocketConnection))
    except TypeError:
        return False

from redis.exceptions import RedisError
try:
    pool = redis.ConnectionPool(connection_class=cls, maint_notifications_config=cfg, **kw)
except RedisError as e:
    if "not supported with" in str(e):
        cfg = MaintNotificationsConfig(enabled=False)
        pool = redis.ConnectionPool(connection_class=cls, maint_notifications_config=cfg, **kw)
    else:
        raise

When it happens

Trigger: Constructing a pool with connection_class=UnixDomainSocketConnection (or a custom class not derived from MaintNotificationsAbstractConnection) while passing an enabled MaintNotificationsConfig. Unix sockets and custom transports are explicitly excluded.

Common situations: Enabling maintenance notifications globally in shared config that is then applied to a UDS-based pool; using a custom connection class for testing/specialized transports and inheriting notifications config; mixing notification config into a pool meant for local unix-socket Redis.

Related errors

• Invalid SSL Certificate Requirements Flag: {ssl_cert_reqs}
• Redis URL must specify one of the following schemes (redis:/
• Invalid value for '{name}' in connection URL.
• Maintenance notifications handlers on connection are only su
• Cannot disable maintenance notifications after enabling them

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