redis/redis-py · error · RedisError

Maintenance notifications are only supported with RESP versi

Error message

Maintenance notifications are only supported with RESP version 3

What it means

Raised by RedisCluster.__init__ (redis/asyncio/cluster.py:572) when maint_notifications_config is enabled but the protocol is not RESP3 — the cluster-side mirror of [40]. Maintenance notifications are RESP3 push messages; the cluster client validates this before constructing NodesManager so a bad config does not leak an open manager. Raises RedisError.

Source

Thrown at redis/asyncio/cluster.py:572

        # Build the client-level HIMPORT registry once (always empty at construction)
        # and share the same object with every node connection. It rides in
        # connection_kwargs -> ClusterNode -> each node's Connection, so the registry is
        # shared cluster-wide and runtime himport_prepare mutates one object. (Async has
        # no per-node Redis client, so the object flows via connection_kwargs directly to
        # the Connection, which is internal plumbing, not a public param.)
        self._himport_registry = HImportRegistry()
        kwargs["himport_registry"] = self._himport_registry

        self.connection_kwargs = kwargs

        # Validate maint_notifications_config before NodesManager is constructed
        # so that a bad config doesn't leak an open NodesManager.
        if (
            maint_notifications_config
            and maint_notifications_config.enabled
            and not check_protocol_version(protocol, 3)
        ):
            raise RedisError(
                "Maintenance notifications are only supported with RESP version 3"
            )
        if check_protocol_version(protocol, 3) and maint_notifications_config is None:
            maint_notifications_config = MaintNotificationsConfig()
        # Initialize to None so aclose() and any error-path code never sees an
        # unset slot, even if __init__ raises before the mixin runs.
        self._oss_cluster_maint_notifications_handler = None

        if startup_nodes:
            passed_nodes = []
            for node in startup_nodes:
                passed_nodes.append(
                    ClusterNode(node.host, node.port, **self.connection_kwargs)
                )
            startup_nodes = passed_nodes
        else:
            startup_nodes = []
        if host and port:

View on GitHub (pinned to da03cdc7e8)

Solutions

1. Set protocol=3 on the RedisCluster constructor.
2. If RESP3 is unavailable, disable maintenance notifications (enabled=False or omit the config).
3. Confirm every cluster node runs Redis >= 6 (RESP3 support) before enabling.

Example fix

// before
c = RedisCluster(host='localhost', port=16379, protocol=2,
    maint_notifications_config=MaintNotificationsConfig(enabled=True))
// after
c = RedisCluster(host='localhost', port=16379, protocol=3,
    maint_notifications_config=MaintNotificationsConfig(enabled=True))

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 for cluster maintenance notifications')
c = RedisCluster(host=host, port=port, protocol=protocol, maint_notifications_config=maint_cfg)

When it happens

Trigger: Constructing RedisCluster(..., maint_notifications_config=MaintNotificationsConfig(enabled=True), protocol=2). The guard checks enabled and not check_protocol_version(protocol, 3).

Common situations: Enabling maintenance notifications in a cluster deployment pinned to RESP2; copying a maintenance example into protocol=2 code.

Related errors

• Maintenance notifications handlers on connection are only su
• Argument 'db' must be 0 or None in cluster mode
• Unix domain socket is not supported in cluster mode
• RedisCluster requires at least one node to discover the clus
• READONLY command failed

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