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 but no parser argument was supplied to the method. The push handlers must be attached to a concrete parser instance; without one the library cannot wire up the notification callbacks.

Source

Thrown at redis/asyncio/connection.py:245

        orig_host_address: str | None = None,
        orig_socket_timeout: float | None = None,
        orig_socket_connect_timeout: float | None = None,
        oss_cluster_maint_notifications_handler: (
            AsyncOSSMaintNotificationsHandler | None
        ) = None,
        parser: BaseParser | None = None,
    ) -> None:
        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, _AsyncHiredisParser) and not isinstance(
            parser, _AsyncRESP3Parser
        ):
            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

If you subclass Connection, always forward the parser= argument into _configure_maintenance_notifications when maintenance notifications are enabled.
Use the public Redis()/from_url() constructors so the parser is wired automatically.
Disable maintenance notifications if you don't need them, to avoid the internal wiring path entirely.

Defensive patterns

Strategy: validation

Validate before calling

# For Connection subclasses overriding the reconnect path:
if self.maint_notifications_config.enabled and parser is None:
    raise RuntimeError('parser= is required when maintenance notifications are enabled')

Try / catch

from redis.exceptions import RedisError
try:
    self._configure_maintenance_notifications(..., parser=parser)
except RedisError as e:
    if 'a parser must be provided' in str(e):
        parser = self._get_parser(); self._configure_maintenance_notifications(..., parser=parser)

Prevention

Forward parser= into _configure_maintenance_notifications in subclasses.
Prefer the public constructors; don't call internal hooks directly.

When it happens

Trigger: An internal/subclass call to _configure_maintenance_notifications that omits the parser= argument while maint_notifications_config.enabled is truthy. Not typically reachable through the public API unless a custom Connection subclass overrides connect() or disconnect()/reconnect wiring.

Common situations: Subclassing the async Connection and overriding the reconnect path while forgetting to forward parser=; calling internal hooks directly in tests or custom connection factories.

Related errors

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