redis/redis-py · error · RedisError

Maintenance notifications handlers on connection are only…

Error message

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

What it means

Raised as RedisError by MaintNotificationsAbstractConnectionPool.__init__ when a maint_notifications_config with enabled=True is supplied but the negotiated protocol is not RESP3 (check_protocol_version returns False). Maintenance notifications are delivered by the server as RESP3 push messages, so they cannot work over RESP2. The check uses check_protocol_version which treats None/SENTINEL as the DEFAULT_RESP_VERSION.

Solutions

Set protocol=3 (or omit it, since RESP3 is the default) when you want maintenance notifications.
If you must stay on RESP2, pass MaintNotificationsConfig(enabled=False) or omit the config.
Validate protocol before construction: ensure check_protocol_version(protocol, 3) is True when maintenance is enabled.

Example fix

# before
pool = ConnectionPool(protocol=2, maint_notifications_config=MaintNotificationsConfig(enabled=True))
# after
pool = ConnectionPool(protocol=3, maint_notifications_config=MaintNotificationsConfig(enabled=True))

Defensive patterns

Strategy: validation

Validate before calling

from redis.utils import check_protocol_version

if maint_cfg.get('enabled') and not check_protocol_version(protocol, 3):
    raise ValueError('Maintenance notifications require RESP3 (protocol=3)')

pool = ConnectionPool(protocol=protocol, maint_notifications_config=maint_cfg_obj)

Type guard

from redis.utils import check_protocol_version

def maint_notifications_compatible(protocol, enabled: bool) -> bool:
    return (not enabled) or check_protocol_version(protocol, 3)

Try / catch

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

Prevention

Default to protocol=3 (the library default) when using maintenance notifications.
Validate protocol in config before constructing the pool.
Don't pin protocol=2 globally if any client uses maintenance notifications.

When it happens

Trigger: Constructing a pool/client with protocol=2 (or protocol='2') together with MaintNotificationsConfig(enabled=True). Also when protocol is an unparseable string and the default resolves to non-3.

Common situations: Forcing RESP2 for compatibility while trying to use maintenance notifications. Mixing a global protocol=2 test matrix with a maintenance-enabled client. Passing protocol as a non-numeric string.

Related errors

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

Appendix: source

Thrown at redis/connection.py:2487

    """

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