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 during Redis.__init__ when maintenance notifications are enabled but the negotiated protocol version is not RESP3. Maintenance notifications are delivered as RESP3 push messages, so they require protocol=3. check_protocol_version(protocol, 3) returns False for protocol 2 or the library default if it resolves to non-3, triggering the error.

Solutions

Set protocol=3 when enabling maintenance notifications.
Disable maintenance notifications if you must stay on RESP2.
Confirm the Redis server supports RESP3 (Redis 6+).

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

if maint_notifications_config and maint_notifications_config.enabled and protocol not in (3, "3"):
    raise ValueError("maintenance notifications require protocol=3")

Prevention

Pair maintenance notifications with protocol=3 always.
Centralize protocol/feature compatibility checks in a config builder.

When it happens

Trigger: Constructing Redis(maint_notifications_config=..., protocol=2) or omitting protocol while the effective default is not 3, with maint_notifications_config.enabled True. The check at client.py:489-494 fires during pool kwargs assembly.

Common situations: Enabling maintenance notifications on a client pinned to RESP2 for compatibility. Forgetting to set protocol=3 in a config that enables notifications. An environment/library version where the default protocol is not 3.

Related errors

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

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