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

Maintenance notifications rely on the server's CLIENT MAINT_NOTIFICATIONS push mechanism, which only exists over the RESP3 wire protocol. The async connection pool raises RedisError when maintenance notifications are explicitly enabled (or an enabled config is passed) while the connection resolves to a non-RESP3 protocol (e.g. protocol=2). The default auto-enable is skipped entirely on RESP2, so this only fires when the user insists on enabling notifications on a RESP2 connection.

Solutions

Set protocol=3 (or omit protocol to use the RESP3 default) so the server can push maintenance notifications.
If you must stay on RESP2, do not pass an enabled maint_notifications_config.
Upgrade the Redis server to a version that supports RESP3 (>=7.x).

Example fix

# before
pool = ConnectionPool(host='redis.local', protocol=2,
                    maint_notifications_config=MaintNotificationsConfig(enabled=True))
# after
pool = ConnectionPool(host='redis.local', protocol=3,
                    maint_notifications_config=MaintNotificationsConfig(enabled=True))

Defensive patterns

Strategy: validation

Validate before calling

from redis.utils import check_protocol_version
if enabled_maint and not check_protocol_version(protocol, 3):
    raise ConfigError('Maintenance notifications require RESP3; set protocol=3 or disable them.')

Prevention

Centralise client construction so protocol and maint_notifications_config are validated together.
Treat protocol=2 and maintenance notifications as mutually exclusive in config checks.

When it happens

Trigger: Constructing an async client/ConnectionPool (or calling update_maint_notifications_config) with both a maint_notifications_config whose enabled=True AND protocol=2; or RESP2 set while explicitly passing an enabled MaintNotificationsConfig. The check at redis/asyncio/connection.py:1944 (is_protocol_supported == False) fires only after the connection-support checks pass.

Common situations: Downgrading to protocol=2 to get RESP2-style response shapes while keeping maintenance notifications on; copy-pasting a RESP3 notifications config into a RESP2 client; targeting a Redis server older than 7.x that has no RESP3 support.

Related errors

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

Appendix: source

Thrown at redis/asyncio/connection.py:1945

                            connection_class, "__name__", connection_class
                        )
                        raise RedisError(
                            "Maintenance notifications are not supported for "
                            f"connection class {connection_class_name}"
                        )

                    # TCP-like connections still need a host to identify the
                    # endpoint that can move during maintenance.
                    raise RedisError(
                        "Maintenance notifications are not supported for connections "
                        "without a host"
                    )
                self._maint_notifications_pool_handler = None
                self._oss_cluster_maint_notifications_handler = None
                return

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

            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
            else:
                self._oss_cluster_maint_notifications_handler = None
                self._maint_notifications_pool_handler = (
                    AsyncMaintNotificationsPoolHandler(self, maint_notifications_config)
                )
                self._update_connection_kwargs_for_maint_notifications(
                    maint_notifications_pool_handler=self._maint_notifications_pool_handler

View on GitHub (pinned to 6a6b581b48)