{"id":"d461f7138c75e80e","repo":"redis/redis-py","slug":"maintenance-notifications-handlers-on-connection-a-d461f7","errorCode":null,"errorMessage":"Maintenance notifications handlers on connection are only supported with RESP version 3","messagePattern":"Maintenance notifications handlers on connection are only supported with RESP version 3","errorType":"exception","errorClass":"RedisError","httpStatus":null,"severity":"error","filePath":"redis/connection.py","lineNumber":2472,"sourceCode":"    \"\"\"\n\n    def __init__(\n        self,\n        maint_notifications_config: Optional[MaintNotificationsConfig] = None,\n        oss_cluster_maint_notifications_handler: Optional[\n            OSSMaintNotificationsHandler\n        ] = None,\n        **kwargs,\n    ):\n        # Initialize maintenance notifications\n        is_protocol_supported = check_protocol_version(kwargs.get(\"protocol\"), 3)\n\n        if maint_notifications_config is None and is_protocol_supported:\n            maint_notifications_config = MaintNotificationsConfig()\n\n        if maint_notifications_config and maint_notifications_config.enabled:\n            if not is_protocol_supported:\n                raise RedisError(\n                    \"Maintenance notifications handlers on connection are only supported with RESP version 3\"\n                )\n\n            self._event_dispatcher = kwargs.get(\"event_dispatcher\", None)\n            if self._event_dispatcher is None:\n                self._event_dispatcher = EventDispatcher()\n\n            self._maint_notifications_pool_handler = MaintNotificationsPoolHandler(\n                self, maint_notifications_config\n            )\n            if oss_cluster_maint_notifications_handler:\n                self._oss_cluster_maint_notifications_handler = (\n                    oss_cluster_maint_notifications_handler\n                )\n                self._update_connection_kwargs_for_maint_notifications(\n                    oss_cluster_maint_notifications_handler=self._oss_cluster_maint_notifications_handler\n                )\n                self._maint_notifications_pool_handler = None","sourceCodeStart":2454,"sourceCodeEnd":2490,"githubUrl":"https://github.com/redis/redis-py/blob/da03cdc7e8731092b13e395605c3c1fb2de25de1/redis/connection.py#L2454-L2490","documentation":"Raised as a RedisError by MaintNotificationsAbstractConnectionPool.__init__ (connection.py:2470-2474) when a maint_notifications_config with enabled=True is supplied but the negotiated protocol is not RESP3 (check_protocol_version at line 2465 returns False for protocol != 3). Maintenance notifications are delivered as RESP3 push messages, so they cannot work over RESP2.","triggerScenarios":"Constructing a ConnectionPool/Redis client with an enabled MaintNotificationsConfig while protocol=2 (or any non-3 value). Note: when protocol is None/SENTINEL it defaults to RESP3 (DEFAULT_RESP_VERSION=3), so this only triggers when RESP2 is explicitly selected.","commonSituations":"Explicitly forcing protocol=2 for compatibility with an older Redis server while also trying to enable maintenance notifications; copying config that sets protocol=2 from a legacy deployment; a config layer that hard-codes protocol=2.","solutions":["Set protocol=3 (or omit it to use the RESP3 default) when maintenance notifications are enabled.","If the server does not support RESP3, disable maintenance notifications (pass MaintNotificationsConfig(enabled=False) or omit the config).","Confirm the target Redis server version supports RESP3 (Redis >= 6)."],"exampleFix":"# before\nfrom redis.maint_notifications import MaintNotificationsConfig\npool = redis.ConnectionPool(\n    protocol=2,\n    maint_notifications_config=MaintNotificationsConfig(enabled=True),\n)\n\n# after\npool = redis.ConnectionPool(\n    protocol=3,\n    maint_notifications_config=MaintNotificationsConfig(enabled=True),\n)","handlingStrategy":"validation","validationCode":"from redis.utils import check_protocol_version\nfrom redis.maint_notifications import MaintNotificationsConfig\n\ncfg = MaintNotificationsConfig(enabled=True)\nif cfg.enabled and not check_protocol_version(protocol, 3):\n    raise ValueError(\"Maintenance notifications require protocol=3\")\n\npool = redis.ConnectionPool(protocol=protocol, maint_notifications_config=cfg)","typeGuard":"def maint_notifications_compatible(protocol) -> bool:\n    from redis.utils import check_protocol_version\n    return check_protocol_version(protocol, 3)","tryCatchPattern":"from redis.exceptions import RedisError\ntry:\n    pool = redis.ConnectionPool(protocol=protocol, maint_notifications_config=cfg)\nexcept RedisError as e:\n    if \"only supported with RESP version 3\" in str(e):\n        pool = redis.ConnectionPool(protocol=3, maint_notifications_config=cfg)\n    else:\n        raise","preventionTips":["Pair maintenance-notification config with protocol=3 in shared config defaults.","Confirm Redis server version >= 6 supports RESP3 before enabling.","Document the RESP3 requirement wherever notifications are configured."],"tags":["resp3","maintenance-notifications","configuration","validation"],"analyzedSha":"da03cdc7e8731092b13e395605c3c1fb2de25de1","analyzedAt":"2026-08-04T20:26:47.563Z","schemaVersion":2}