redis/redis-py · error · RedisError

Maintenance notifications handlers on connection are only su

Error message

Maintenance notifications handlers on connection are only supported with RESP version 3

What it means

Raised as a RedisError by MaintNotificationsAbstractConnectionPool.__init__ (connection.py:2470-2474) when a maint_notifications_config with enabled=True is supplied but the negotiated protocol is not RESP3 (check_protocol_version at line 2465 returns False for protocol != 3). Maintenance notifications are delivered as RESP3 push messages, so they cannot work over RESP2.

Source

Thrown at redis/connection.py:2472

    """

    def __init__(
        self,
        maint_notifications_config: Optional[MaintNotificationsConfig] = None,
        oss_cluster_maint_notifications_handler: Optional[
            OSSMaintNotificationsHandler
        ] = None,
        **kwargs,
    ):
        # Initialize maintenance notifications
        is_protocol_supported = check_protocol_version(kwargs.get("protocol"), 3)

        if maint_notifications_config is None and is_protocol_supported:
            maint_notifications_config = MaintNotificationsConfig()

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

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

            self._maint_notifications_pool_handler = MaintNotificationsPoolHandler(
                self, maint_notifications_config
            )
            if oss_cluster_maint_notifications_handler:
                self._oss_cluster_maint_notifications_handler = (
                    oss_cluster_maint_notifications_handler
                )
                self._update_connection_kwargs_for_maint_notifications(
                    oss_cluster_maint_notifications_handler=self._oss_cluster_maint_notifications_handler
                )
                self._maint_notifications_pool_handler = None

View on GitHub (pinned to da03cdc7e8)

Solutions

Set protocol=3 (or omit it to use the RESP3 default) when maintenance notifications are enabled.
If the server does not support RESP3, disable maintenance notifications (pass MaintNotificationsConfig(enabled=False) or omit the config).
Confirm the target Redis server version supports RESP3 (Redis >= 6).

Example fix

# before
from redis.maint_notifications import MaintNotificationsConfig
pool = redis.ConnectionPool(
    protocol=2,
    maint_notifications_config=MaintNotificationsConfig(enabled=True),
)

# after
pool = redis.ConnectionPool(
    protocol=3,
    maint_notifications_config=MaintNotificationsConfig(enabled=True),
)

Defensive patterns

Strategy: validation

Validate before calling

from redis.utils import check_protocol_version
from redis.maint_notifications import MaintNotificationsConfig

cfg = MaintNotificationsConfig(enabled=True)
if cfg.enabled and not check_protocol_version(protocol, 3):
    raise ValueError("Maintenance notifications require protocol=3")

pool = redis.ConnectionPool(protocol=protocol, maint_notifications_config=cfg)

Type guard

def maint_notifications_compatible(protocol) -> bool:
    from redis.utils import check_protocol_version
    return check_protocol_version(protocol, 3)

Try / catch

from redis.exceptions import RedisError
try:
    pool = redis.ConnectionPool(protocol=protocol, maint_notifications_config=cfg)
except RedisError as e:
    if "only supported with RESP version 3" in str(e):
        pool = redis.ConnectionPool(protocol=3, maint_notifications_config=cfg)
    else:
        raise

Prevention

Pair maintenance-notification config with protocol=3 in shared config defaults.
Confirm Redis server version >= 6 supports RESP3 before enabling.
Document the RESP3 requirement wherever notifications are configured.

When it happens

Trigger: Constructing a ConnectionPool/Redis client with an enabled MaintNotificationsConfig while protocol=2 (or any non-3 value). Note: when protocol is None/SENTINEL it defaults to RESP3 (DEFAULT_RESP_VERSION=3), so this only triggers when RESP2 is explicitly selected.

Common situations: Explicitly forcing protocol=2 for compatibility with an older Redis server while also trying to enable maintenance notifications; copying config that sets protocol=2 from a legacy deployment; a config layer that hard-codes protocol=2.

Related errors

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