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 when maintenance notifications are connection-supported (TCP + supported class + host) but the configured RESP protocol is not version 3. The maintenance-notifications feature uses RESP3 push types and the CLIENT MAINT_NOTIFICATIONS command, both requiring RESP3. The check at line 1941 uses check_protocol_version(protocol, 3).

Source

Thrown at redis/asyncio/connection.py:1942

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

Solutions

Use protocol=3 (the current library default) when enabling maintenance notifications.
Upgrade the Redis server to 6.0+ (RESP3 / HELLO support).
Disable maintenance notifications if RESP3 is not available in your deployment.

Example fix

// before
r = redis.asyncio.Redis(host=h, port=p, protocol=2,
    maint_notifications_config=MaintNotificationsConfig(enabled=True))

// after
r = redis.asyncio.Redis(host=h, port=p, protocol=3,
    maint_notifications_config=MaintNotificationsConfig(enabled=True))

Defensive patterns

Strategy: validation

Validate before calling

def protocol_supports_maint_notifications(protocol: int | None) -> bool:
    return protocol == 3 or protocol is None  # None resolves to 3 (default)

Type guard

def is_resp3(protocol) -> bool:
    return protocol == 3

Try / catch

from redis.exceptions import RedisError
try:
    r = redis.asyncio.Redis(host=h, port=p, protocol=proto, maint_notifications_config=cfg)
except RedisError as e:
    if "RESP version 3" in str(e):
        r = redis.asyncio.Redis(host=h, port=p, protocol=3, maint_notifications_config=cfg)
    else:
        raise

Prevention

Use protocol=3 (the default) when enabling maintenance notifications.
Ensure the server is Redis 6.0+ for RESP3.
Don't pin protocol=2 globally if any client uses maintenance notifications.

When it happens

Trigger: Constructing a client/pool with protocol=2 (or the default resolved to 2) together with maint_notifications_config enabled=True, while the connection otherwise qualifies (TCP, host, supported class). Also when a rediss/redis URL forces an older protocol via ?protocol=2.

Common situations: Connecting to a Redis older than 6.0 (no RESP3) with the feature enabled; explicitly pinning protocol=2 for compatibility; env/config setting protocol=2 globally while enabling maintenance notifications.

Related errors

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