{"record":{"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":2487,"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":2469,"sourceCodeEnd":2505,"githubUrl":"https://github.com/redis/redis-py/blob/6a6b581b48225afa0b76912d1028c6035baee932/redis/connection.py#L2469-L2505","documentation":"Raised as RedisError by MaintNotificationsAbstractConnectionPool.__init__ when a maint_notifications_config with enabled=True is supplied but the negotiated protocol is not RESP3 (check_protocol_version returns False). Maintenance notifications are delivered by the server as RESP3 push messages, so they cannot work over RESP2. The check uses check_protocol_version which treats None/SENTINEL as the DEFAULT_RESP_VERSION.","triggerScenarios":"Constructing a pool/client with protocol=2 (or protocol='2') together with MaintNotificationsConfig(enabled=True). Also when protocol is an unparseable string and the default resolves to non-3.","commonSituations":"Forcing RESP2 for compatibility while trying to use maintenance notifications. Mixing a global protocol=2 test matrix with a maintenance-enabled client. Passing protocol as a non-numeric string.","solutions":["Set protocol=3 (or omit it, since RESP3 is the default) when you want maintenance notifications.","If you must stay on RESP2, pass MaintNotificationsConfig(enabled=False) or omit the config.","Validate protocol before construction: ensure check_protocol_version(protocol, 3) is True when maintenance is enabled."],"exampleFix":"# before\npool = ConnectionPool(protocol=2, maint_notifications_config=MaintNotificationsConfig(enabled=True))\n# after\npool = ConnectionPool(protocol=3, maint_notifications_config=MaintNotificationsConfig(enabled=True))","handlingStrategy":"validation","validationCode":"from redis.utils import check_protocol_version\n\nif maint_cfg.get('enabled') and not check_protocol_version(protocol, 3):\n    raise ValueError('Maintenance notifications require RESP3 (protocol=3)')\n\npool = ConnectionPool(protocol=protocol, maint_notifications_config=maint_cfg_obj)","typeGuard":"from redis.utils import check_protocol_version\n\ndef maint_notifications_compatible(protocol, enabled: bool) -> bool:\n    return (not enabled) or check_protocol_version(protocol, 3)","tryCatchPattern":"from redis.exceptions import RedisError\ntry:\n    pool = ConnectionPool(protocol=protocol, maint_notifications_config=cfg)\nexcept RedisError as e:\n    if 'only supported with RESP version 3' in str(e):\n        pool = ConnectionPool(protocol=3, maint_notifications_config=cfg)\n    else:\n        raise","preventionTips":["Default to protocol=3 (the library default) when using maintenance notifications.","Validate protocol in config before constructing the pool.","Don't pin protocol=2 globally if any client uses maintenance notifications."],"tags":["maintenance-notifications","resp3","configuration"],"backgroundTag":null,"analyzedSha":"6a6b581b48225afa0b76912d1028c6035baee932","analyzedAt":"2026-08-10T12:52:44.840Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}