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 RedisError in Redis.__init__ (redis/client.py:492) when maint_notifications_config.enabled is True but the negotiated protocol is not RESP3. Maintenance-notification handlers rely on RESP3 server-pushed messages (push types), which do not exist in RESP2, so the client rejects the combination at construction.

Source

Thrown at redis/client.py:492

                            "ssl_ocsp_expected_cert": ssl_ocsp_expected_cert,
                            "ssl_min_version": ssl_min_version,
                            "ssl_ciphers": ssl_ciphers,
                        }
                    )
                if (cache_config or cache) and check_protocol_version(protocol, 3):
                    kwargs.update(
                        {
                            "cache": cache,
                            "cache_config": cache_config,
                        }
                    )
                maint_notifications_enabled = (
                    maint_notifications_config and maint_notifications_config.enabled
                )
                if maint_notifications_enabled and not check_protocol_version(
                    protocol, 3
                ):
                    raise RedisError(
                        "Maintenance notifications handlers on connection are only supported with RESP version 3"
                    )
                if maint_notifications_config:
                    kwargs.update(
                        {
                            "maint_notifications_config": maint_notifications_config,
                        }
                    )
                if oss_cluster_maint_notifications_handler:
                    kwargs.update(
                        {
                            "oss_cluster_maint_notifications_handler": oss_cluster_maint_notifications_handler,
                        }
                    )
            connection_pool = ConnectionPool(**kwargs)
            self._event_dispatcher.dispatch(
                AfterPooledConnectionsInstantiationEvent(
                    [connection_pool], ClientType.SYNC, credential_provider

View on GitHub (pinned to da03cdc7e8)

Solutions

1. Set protocol=3 when enabling maintenance notifications.
2. Upgrade the Redis server to >=7.0 (RESP3-capable) if needed.
3. Disable maintenance notifications if you must stay on RESP2.

Example fix

# before
r = Redis(host='localhost', protocol=2,
         maint_notifications_config=MaintNotificationsConfig(enabled=True))  # RedisError
# after
r = Redis(host='localhost', protocol=3,
         maint_notifications_config=MaintNotificationsConfig(enabled=True))

from redis._parsers.helpers import check_protocol_version
if maint_notifications_config.enabled and not check_protocol_version(protocol, 3):
    raise ConfigError('Maintenance notifications require protocol=3')

def resp3_enabled(protocol) -> bool:
    from redis._parsers.helpers import check_protocol_version
    return check_protocol_version(protocol, 3)

try:
    r = Redis(protocol=protocol, maint_notifications_config=cfg)
except RedisError as e:
    logger.error('need RESP3 for maint notifications: %s', e)
    raise

When it happens

Trigger: Constructing Redis with maint_notifications_config.enabled=True and protocol omitted/2 (or a server that negotiates RESP2); explicitly setting protocol=2 with maint notifications on.

Common situations: Defaulting protocol while enabling maint notifications on an older Redis that only speaks RESP2; explicitly pinning protocol=2 elsewhere in config; template enabling maint notifications without bumping protocol.

Related errors

• Maintenance notifications are only supported with hiredis an
• Maintenance notifications handlers on connection are only su
• Maintenance notifications are only supported with hiredis an
• Maintenance notifications handlers on connection are only su
• Maintenance notifications are only supported with RESP versi

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