redis/redis-py · error · RedisError

To configure maintenance notifications, a parser must be pro

Error message

To configure maintenance notifications, a parser must be provided!

What it means

Raised by AbstractConnection._configure_maintenance_notifications when maintenance notifications are enabled in config but no parser instance was passed to the method. The parser is required to wire push-notification handling. This is primarily an internal/programmatic error: the connection plumbing did not supply the parser when enabling notifications. Raised as a generic RedisError.

Source

Thrown at redis/connection.py:486

        parser: Optional[BaseParser] = None,
    ):
        """
        Enable maintenance notifications by setting up
        handlers and storing original connection parameters.

        Should be used ONLY with parsers that support push notifications.
        """
        if (
            not self.maint_notifications_config
            or not self.maint_notifications_config.enabled
        ):
            self._maint_notifications_pool_handler = None
            self._maint_notifications_connection_handler = None
            self._oss_cluster_maint_notifications_handler = None
            return

        if not parser:
            raise RedisError(
                "To configure maintenance notifications, a parser must be provided!"
            )

        if not isinstance(parser, _HiredisParser) and not isinstance(
            parser, _RESP3Parser
        ):
            raise RedisError(
                "Maintenance notifications are only supported with hiredis and RESP3 parsers!"
            )

        if maint_notifications_pool_handler:
            # Extract a reference to a new pool handler that copies all properties
            # of the original one and has a different connection reference
            # This is needed because when we attach the handler to the parser
            # we need to make sure that the handler has a reference to the
            # connection that the parser is attached to.
            self._maint_notifications_pool_handler = (
                maint_notifications_pool_handler.get_handler_for_connection()

View on GitHub (pinned to da03cdc7e8)

Solutions

Pass the connection's parser when enabling notifications: _configure_maintenance_notifications(..., parser=self._get_parser()).
Use the standard client construction path (RedisCluster with maint_notifications_config) instead of calling the internal method directly.
If notifications are not actually needed, disable them so the method early-returns before the parser check.

Example fix

// before
conn._configure_maintenance_notifications(cfg, parser=None)
// after
conn._configure_maintenance_notifications(cfg, parser=conn._get_parser())

Defensive patterns

Strategy: validation

Validate before calling

def configure_maint(conn, cfg, parser=None):
    if cfg and getattr(cfg, 'enabled', False) and parser is None:
        parser = conn._get_parser()
    conn._configure_maintenance_notifications(cfg, parser=parser)

Type guard

def parser_supplied(parser) -> bool:
    return parser is not None

Try / catch

try:
    conn._configure_maintenance_notifications(cfg, parser=None)
except Exception as e:
    if 'a parser must be provided' in str(e):
        conn._configure_maintenance_notifications(cfg, parser=conn._get_parser())
    else:
        raise

Prevention

Avoid calling _configure_maintenance_notifications directly; use standard client construction.
If you must, always forward parser=self._get_parser().
Disable notifications in config when not needed.

When it happens

Trigger: Calling connection._configure_maintenance_notifications(...) with a config whose .enabled is True but parser=None. Typically hit by custom connection subclasses or reconnection paths that forgot to forward the parser, not by normal client construction.

Common situations: Subclassing AbstractConnection and overriding/replaying reconnection logic without passing the parser; manually invoking the config method during custom pool wiring; a bug in a fork/monkeypatch of the connection layer.

Related errors

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