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

Raised by AbstractConnection._get_push_notifications_parser() when the active parser is not a HiredisParser or RESP3 (_RESP3Parser). Maintenance (push) notifications require a parser that understands RESP3 push messages, so a pure RESP2 parser cannot be used to read them.

Solutions

Use protocol=3 (RESP3) so the RESP3 parser is selected.
Install hiredis (pip install redis[hiredis]) so the hiredis parser is available.
Disable maintenance notifications if you cannot move to RESP3/hiredis.

Example fix

// before
client = Redis(host=..., protocol=2,
    # maint notifications enabled elsewhere
)
// after
client = Redis(host=..., protocol=3)
# and ensure hiredis is installed: pip install redis[hiredis]

Defensive patterns

Strategy: validation

Validate before calling

from redis.connection import _HiredisParser, _RESP3Parser
parser = conn._get_parser()
if not isinstance(parser, (_HiredisParser, _RESP3Parser)):
    raise RuntimeError('enable RESP3/hiredis to use maintenance notifications')

Type guard

from redis.connection import _HiredisParser, _RESP3Parser

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

Try / catch

try:
    conn._get_push_notifications_parser()
except RedisError:
    # fall back to non-maintenance path or reconfigure protocol
    raise

Prevention

Standardize on protocol=3 when using maintenance notifications.
Install the hiredis extra in production images.

When it happens

Trigger: Triggering maintenance-notification handling (e.g., enabling oss_cluster maint notifications) on a connection whose parser is the pure-Python RESP2 parser. This happens when protocol=2 is in effect or hiredis is unavailable and protocol defaulted to RESP2.

Common situations: OSS cluster maint-notification feature enabled without ensuring RESP3/hiredis. Forcing protocol=2 globally. Environment without hiredis installed where the feature expects it.

Related errors

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

Appendix: 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 6a6b581b48)