{"id":"d2f7beaaaeee166d","repo":"redis/redis-py","slug":"maintenance-notifications-are-only-supported-with-d2f7be","errorCode":null,"errorMessage":"Maintenance notifications are only supported with hiredis and RESP3 parsers!","messagePattern":"Maintenance notifications are only supported with hiredis and RESP3 parsers!","errorType":"exception","errorClass":"RedisError","httpStatus":null,"severity":"error","filePath":"redis/connection.py","lineNumber":386,"sourceCode":"        self._configure_maintenance_notifications(\n            maint_notifications_pool_handler,\n            orig_host_address,\n            orig_socket_timeout,\n            orig_socket_connect_timeout,\n            oss_cluster_maint_notifications_handler,\n            parser,\n        )\n        self._processed_start_maint_notifications = set()\n        self._skipped_end_maint_notifications = set()\n\n    @abstractmethod\n    def _get_parser(self) -> BaseParser:\n        pass\n\n    def _get_push_notifications_parser(self) -> Union[_HiredisParser, _RESP3Parser]:\n        parser = self._get_parser()\n        if not isinstance(parser, (_HiredisParser, _RESP3Parser)):\n            raise RedisError(\n                \"Maintenance notifications are only supported with hiredis and RESP3 parsers!\"\n            )\n        return parser\n\n    @abstractmethod\n    def _get_socket(self) -> Optional[socket.socket]:\n        pass\n\n    @abstractmethod\n    def get_protocol(self) -> Union[int, str]:\n        \"\"\"\n        Returns:\n            The RESP protocol version, or ``None`` if the protocol is not specified,\n            in which case the server default will be used.\n        \"\"\"\n        pass\n\n    @property","sourceCodeStart":368,"sourceCodeEnd":404,"githubUrl":"https://github.com/redis/redis-py/blob/da03cdc7e8731092b13e395605c3c1fb2de25de1/redis/connection.py#L368-L404","documentation":"Raised by AbstractConnection._get_push_notifications_parser when maintenance notifications are requested but the active parser is neither the hiredis parser nor the pure-Python RESP3 parser. Push notifications (used for OSS cluster maintenance events) require RESP3 or hiredis-with-RESP3; the RESP2 parsers do not support push frames. Raised as a generic RedisError.","triggerScenarios":"Enabling OSS cluster maintenance notifications while the connection uses protocol=2 (RESP2) or the pure-Python RESP2 parser, e.g. RedisCluster(..., maint_notifications_config=..., protocol=2) without hiredis. The check fires when the connection tries to obtain its push-notification parser.","commonSituations":"Forgetting to install the hiredis extra in production; explicitly setting protocol=2 for compatibility; older server that only speaks RESP2; disabling hiredis via env/flags.","solutions":["Use RESP3: create the client with protocol=3 so the _RESP3Parser (or hiredis RESP3) is selected.","Install hiredis (pip install redis[hiredis]) and use protocol=3 for the fastest push-capable path.","If you do not need maintenance notifications, disable them (maint_notifications_config.enabled=False) to avoid requiring a push-capable parser."],"exampleFix":"// before\nr = RedisCluster(..., protocol=2, maint_notifications_config=cfg)\n// after\nr = RedisCluster(..., protocol=3, maint_notifications_config=cfg)","handlingStrategy":"validation","validationCode":"from redis.connection import _HiredisParser, _RESP3Parser\n\ndef parser_supports_push(parser) -> bool:\n    return isinstance(parser, (_HiredisParser, _RESP3Parser))\n\n# before enabling notifications, ensure protocol=3 / hiredis is active\nif parser_supports_push(conn._get_parser()):\n    enable_maint_notifications()","typeGuard":"from redis.connection import _HiredisParser, _RESP3Parser\n\ndef is_push_capable(parser) -> bool:\n    return isinstance(parser, (_HiredisParser, _RESP3Parser))","tryCatchPattern":"try:\n    parser = conn._get_push_notifications_parser()\nexcept Exception as e:\n    if 'Maintenance notifications' in str(e):\n        # recreate client with protocol=3 and/or install hiredis\n        raise RuntimeError('Enable RESP3 (protocol=3) or install redis[hiredis] to use maintenance notifications')\n    raise","preventionTips":["Create notification-enabled clients with protocol=3.","Install the hiredis extra in environments using maintenance notifications.","Disable maint_notifications_config when stuck on RESP2."],"tags":["connection","parser","resp3","hiredis","maintenance-notifications","cluster","config"],"analyzedSha":"da03cdc7e8731092b13e395605c3c1fb2de25de1","analyzedAt":"2026-08-04T20:26:47.563Z","schemaVersion":2}