{"id":"70f6b7327fc6d5ad","repo":"redis/redis-py","slug":"maintenance-notifications-handlers-on-connection-a-70f6b7","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/asyncio/connection.py","lineNumber":1942,"sourceCode":"                            connection_class, \"__name__\", connection_class\n                        )\n                        raise RedisError(\n                            \"Maintenance notifications are not supported for \"\n                            f\"connection class {connection_class_name}\"\n                        )\n\n                    # TCP-like connections still need a host to identify the\n                    # endpoint that can move during maintenance.\n                    raise RedisError(\n                        \"Maintenance notifications are not supported for connections \"\n                        \"without a host\"\n                    )\n                self._maint_notifications_pool_handler = None\n                self._oss_cluster_maint_notifications_handler = None\n                return\n\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            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\n            else:\n                self._oss_cluster_maint_notifications_handler = None\n                self._maint_notifications_pool_handler = (\n                    AsyncMaintNotificationsPoolHandler(self, maint_notifications_config)\n                )\n                self._update_connection_kwargs_for_maint_notifications(\n                    maint_notifications_pool_handler=self._maint_notifications_pool_handler","sourceCodeStart":1924,"sourceCodeEnd":1960,"githubUrl":"https://github.com/redis/redis-py/blob/da03cdc7e8731092b13e395605c3c1fb2de25de1/redis/asyncio/connection.py#L1924-L1960","documentation":"Raised as a RedisError when maintenance notifications are connection-supported (TCP + supported class + host) but the configured RESP protocol is not version 3. The maintenance-notifications feature uses RESP3 push types and the CLIENT MAINT_NOTIFICATIONS command, both requiring RESP3. The check at line 1941 uses check_protocol_version(protocol, 3).","triggerScenarios":"Constructing a client/pool with protocol=2 (or the default resolved to 2) together with maint_notifications_config enabled=True, while the connection otherwise qualifies (TCP, host, supported class). Also when a rediss/redis URL forces an older protocol via ?protocol=2.","commonSituations":"Connecting to a Redis older than 6.0 (no RESP3) with the feature enabled; explicitly pinning protocol=2 for compatibility; env/config setting protocol=2 globally while enabling maintenance notifications.","solutions":["Use protocol=3 (the current library default) when enabling maintenance notifications.","Upgrade the Redis server to 6.0+ (RESP3 / HELLO support).","Disable maintenance notifications if RESP3 is not available in your deployment."],"exampleFix":"// before\nr = redis.asyncio.Redis(host=h, port=p, protocol=2,\n    maint_notifications_config=MaintNotificationsConfig(enabled=True))\n\n// after\nr = redis.asyncio.Redis(host=h, port=p, protocol=3,\n    maint_notifications_config=MaintNotificationsConfig(enabled=True))","handlingStrategy":"validation","validationCode":"def protocol_supports_maint_notifications(protocol: int | None) -> bool:\n    return protocol == 3 or protocol is None  # None resolves to 3 (default)","typeGuard":"def is_resp3(protocol) -> bool:\n    return protocol == 3","tryCatchPattern":"from redis.exceptions import RedisError\ntry:\n    r = redis.asyncio.Redis(host=h, port=p, protocol=proto, maint_notifications_config=cfg)\nexcept RedisError as e:\n    if \"RESP version 3\" in str(e):\n        r = redis.asyncio.Redis(host=h, port=p, protocol=3, maint_notifications_config=cfg)\n    else:\n        raise","preventionTips":["Use protocol=3 (the default) when enabling maintenance notifications.","Ensure the server is Redis 6.0+ for RESP3.","Don't pin protocol=2 globally if any client uses maintenance notifications."],"tags":["maintenance-notifications","resp3","protocol","config","async"],"analyzedSha":"da03cdc7e8731092b13e395605c3c1fb2de25de1","analyzedAt":"2026-08-04T20:26:47.563Z","schemaVersion":2}