redis/redis-py · error · RedisError

Maintenance notifications are only supported with hiredis an

Error message

Maintenance notifications are only supported with hiredis and RESP3 parsers!

What it means

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.

Source

Thrown at redis/connection.py:386

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

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

    def _get_push_notifications_parser(self) -> Union[_HiredisParser, _RESP3Parser]:
        parser = self._get_parser()
        if not isinstance(parser, (_HiredisParser, _RESP3Parser)):
            raise RedisError(
                "Maintenance notifications are only supported with hiredis and RESP3 parsers!"
            )
        return parser

    @abstractmethod
    def _get_socket(self) -> Optional[socket.socket]:
        pass

    @abstractmethod
    def get_protocol(self) -> Union[int, str]:
        """
        Returns:
            The RESP protocol version, or ``None`` if the protocol is not specified,
            in which case the server default will be used.
        """
        pass

    @property

View on GitHub (pinned to da03cdc7e8)

Solutions

  1. Use RESP3: create the client with protocol=3 so the _RESP3Parser (or hiredis RESP3) is selected.
  2. Install hiredis (pip install redis[hiredis]) and use protocol=3 for the fastest push-capable path.
  3. If you do not need maintenance notifications, disable them (maint_notifications_config.enabled=False) to avoid requiring a push-capable parser.

Example fix

// before
r = RedisCluster(..., protocol=2, maint_notifications_config=cfg)
// after
r = RedisCluster(..., protocol=3, maint_notifications_config=cfg)
Defensive patterns

Strategy: validation

Validate before calling

from redis.connection import _HiredisParser, _RESP3Parser

def parser_supports_push(parser) -> bool:
    return isinstance(parser, (_HiredisParser, _RESP3Parser))

# before enabling notifications, ensure protocol=3 / hiredis is active
if parser_supports_push(conn._get_parser()):
    enable_maint_notifications()

Type guard

from redis.connection import _HiredisParser, _RESP3Parser

def is_push_capable(parser) -> bool:
    return isinstance(parser, (_HiredisParser, _RESP3Parser))

Try / catch

try:
    parser = conn._get_push_notifications_parser()
except Exception as e:
    if 'Maintenance notifications' in str(e):
        # recreate client with protocol=3 and/or install hiredis
        raise RuntimeError('Enable RESP3 (protocol=3) or install redis[hiredis] to use maintenance notifications')
    raise

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of redis/redis-py@da03cdc7e8 (2026-08-04). Data as JSON: /data/errors/d2f7beaaaeee166d.json. Report an issue: GitHub.