redis/redis-py · error · RedisError

To configure maintenance notifications, a parser must be…

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 argument was passed to the method. The push-notification setup needs an existing parser instance to wire up notification reading; a missing parser is treated as an internal wiring error.

Solutions

  1. Pass a valid parser instance (the connection's parser) when calling _configure_maintenance_notifications.
  2. Ensure maint_notifications_config.enabled is False unless your setup supplies a parser.
  3. If you are not intentionally using maintenance notifications, leave them disabled.

Example fix

// before
conn._configure_maintenance_notifications(
    maint_notifications_pool_handler=handler,
    parser=None,
)
// after
conn._configure_maintenance_notifications(
    maint_notifications_pool_handler=handler,
    parser=conn._get_parser(),
)
Defensive patterns

Strategy: validation

Validate before calling

if conn.maint_notifications_config and conn.maint_notifications_config.enabled:
    parser = conn._get_parser()
    assert parser is not None, 'parser required for maint notifications'
conn._configure_maintenance_notifications(parser=parser)

Type guard

from redis.connection import BaseParser

def has_parser(parser) -> bool:
    return parser is not None and isinstance(parser, BaseParser)

Try / catch

try:
    conn._configure_maintenance_notifications(parser=parser)
except RedisError:
    conn._configure_maintenance_notifications(parser=conn._get_parser())

Prevention

When it happens

Trigger: Calling _configure_maintenance_notifications(...) with maint_notifications_config.enabled=True but parser=None. This is generally an internal/library-side wiring path rather than a normal user API.

Common situations: Subclassing or monkey-patching the connection and overriding the maintenance-notification setup without forwarding a parser. Internal code paths that build a connection with maint notifications but forget to pass the parser.

Related errors

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

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