redis/redis-py · error · RedisError

Maintenance notifications are only supported with hiredis…

Error message

Maintenance notifications are only supported with hiredis and RESP3 parsers!

What it means

RedisError from AbstractConnection._get_push_notifications_parser (redis/asyncio/connection.py:191) when the active parser is neither _AsyncHiredisParser nor _AsyncRESP3Parser. Maintenance notifications arrive over the RESP3 push protocol, which only the hiredis and RESP3 parsers can decode. Enabling them under the RESP2 Python parser is unsupported.

Solutions

Use protocol=3 (RESP3) so push notifications are decoded
Install and use hiredis (parser=_AsyncHiredisParser) which supports push notifications on both protocols
Disable maintenance notifications if RESP2 with the Python parser is required

Example fix

// before
Redis(protocol=2, maint_notifications_config=...)
// after
Redis(protocol=3, maint_notifications_config=...)
# or install hiredis and keep protocol default

Defensive patterns

Strategy: validation

Validate before calling

if maint_enabled and protocol == 2 and not hiredis_available:
    raise ValueError('maintenance notifications need RESP3 or hiredis')

Try / catch

try:
    client = Redis(protocol=2, maint_notifications_config=cfg)
except RedisError as e:
    if 'Maintenance notifications' in str(e):
        client = Redis(protocol=3, maint_notifications_config=cfg)

Prevention

Use protocol=3 when enabling maintenance notifications
Install hiredis so both protocols support push notifications

When it happens

Trigger: Constructing an async connection with protocol=2 (RESP2) and maintenance_notifications enabled, or forcing the RESP2 Python parser while maint notifications are on.

Common situations: Forcing protocol=2 for compatibility while also requesting OSS cluster maintenance notifications; misconfigured connection pool used by a multidb/maintenance setup.

Related errors

AI-assisted analysis of redis/redis-py@6a6b581b48 (2026-08-10). Data as JSON: /api/errors/004f4c5667bdc0f2. Report an issue: GitHub.

Appendix: source

Thrown at redis/asyncio/connection.py:194

        self._processed_start_maint_notifications: set[int] = set()
        self._skipped_end_maint_notifications: set[int] = set()
        self._configure_maintenance_notifications(
            maint_notifications_pool_handler,
            orig_host_address,
            orig_socket_timeout,
            orig_socket_connect_timeout,
            oss_cluster_maint_notifications_handler,
            parser,
        )

    @abstractmethod
    def _get_parser(self) -> BaseParser:
        pass

    def _get_push_notifications_parser(self) -> AsyncPushNotificationsParser:
        parser = self._get_parser()
        if not isinstance(parser, (_AsyncHiredisParser, _AsyncRESP3Parser)):
            raise RedisError(
                "Maintenance notifications are only supported with hiredis and RESP3 parsers!"
            )
        return parser

    @abstractmethod
    def get_protocol(self):
        pass

    @abstractmethod
    async def send_command(self, *args: Any, **kwargs: Any) -> None:
        pass

    @abstractmethod
    async def read_response(
        self,
        disable_decoding: bool = False,
        timeout: float | None = None,
        *,

View on GitHub (pinned to 6a6b581b48)