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 in the async Redis client constructor (redis/asyncio/client.py:469) when a MaintenanceNotificationsConfig with enabled=True is supplied but the wire protocol is not RESP3. Maintenance notifications are a RESP3-only server push mechanism, so the library refuses to construct a client that would silently never receive them. It raises a plain RedisError at construction time.

Source

Thrown at redis/asyncio/client.py:469

                            "ssl_keyfile": ssl_keyfile,
                            "ssl_certfile": ssl_certfile,
                            "ssl_cert_reqs": ssl_cert_reqs,
                            "ssl_include_verify_flags": ssl_include_verify_flags,
                            "ssl_exclude_verify_flags": ssl_exclude_verify_flags,
                            "ssl_ca_certs": ssl_ca_certs,
                            "ssl_ca_data": ssl_ca_data,
                            "ssl_ca_path": ssl_ca_path,
                            "ssl_check_hostname": ssl_check_hostname,
                            "ssl_min_version": ssl_min_version,
                            "ssl_ciphers": ssl_ciphers,
                            "ssl_password": ssl_password,
                        }
                    )
            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,
                    }
                )
            # This arg only used if no pool is passed in
            self.auto_close_connection_pool = auto_close_connection_pool
            connection_pool = ConnectionPool(**kwargs)
            self._event_dispatcher.dispatch(
                AfterPooledConnectionsInstantiationEvent(
                    [connection_pool], ClientType.ASYNC, credential_provider
                )
            )
        else:
            # If a pool is passed in, do not close it

View on GitHub (pinned to da03cdc7e8)

Solutions

Pass protocol=3 to the Redis(...) constructor so RESP3 is negotiated and maintenance pushes are delivered.
If you cannot use RESP3, remove the maint_notifications_config argument or set enabled=False.
Verify with `await client.connection_pool.get_connection().on_connect()`/HELLO that the server itself supports RESP3 (Redis >= 6).

Example fix

// before
r = redis.asyncio.Redis(
    protocol=2,
    maint_notifications_config=MaintNotificationsConfig(enabled=True),
)
// after
r = redis.asyncio.Redis(
    protocol=3,
    maint_notifications_config=MaintNotificationsConfig(enabled=True),
)

Defensive patterns

Strategy: validation

Validate before calling

from redis._parsers.helpers import check_protocol_version
if maint_cfg and maint_cfg.enabled and not check_protocol_version(protocol, 3):
    raise ValueError("Enable protocol=3 before enabling maintenance notifications")
r = redis.asyncio.Redis(protocol=protocol, maint_notifications_config=maint_cfg)

Prevention

Centralize client construction in a factory that asserts protocol=3 whenever maintenance notifications are enabled.
Run the protocol x features matrix in CI to catch feature/protocol mismatches early.

When it happens

Trigger: Constructing redis.asyncio.Redis(..., maint_notifications_config=MaintNotificationsConfig(enabled=True)) together with protocol=2 (or omitting protocol in an environment where it resolves to a non-3 default override). The guard fires before any connection is opened, so it is a synchronous init-time failure.

Common situations: Copying a maintenance-notifications example that assumes RESP3 into code that explicitly sets protocol=2 for RESP2 compatibility; upgrading redis-py to use maintenance notifications without bumping the protocol; CI that forces protocol=2 across the matrix while a feature test enables maintenance notifications.

Related errors

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