redis/redis-py · error · ValueError

Cannot disable maintenance notifications after enabling them

Error message

Cannot disable maintenance notifications after enabling them

What it means

Maintenance notifications are a one-way switch on a pool: once enabled, per-connection handlers are wired into every connection's kwargs, and the pool refuses to reverse that by raising ValueError from update_maint_notifications_config. The guard at connection.py:2047-2051 keeps connection state consistent. To turn notifications off you must recreate the pool without them.

Solutions

Recreate the pool/client from scratch without maintenance notifications instead of trying to disable in place.
If you need both modes, keep two pools and route traffic to the right one.
Do not call update_maint_notifications_config with an enabled=False config on an already-enabled pool.

Example fix

# before
await pool.update_maint_notifications_config(MaintNotificationsConfig(enabled=False))
# after
await pool.aclose()
pool = ConnectionPool(host='redis.local', protocol=3)  # no maint config

Defensive patterns

Strategy: validation

Validate before calling

if new_config.enabled is False and pool.maint_notifications_enabled():
    # recreate the pool instead of disabling in place
    raise ConfigError('Recreate the pool to disable maintenance notifications.')

Prevention

Treat maintenance notifications as enable-only per pool lifecycle.
Drive the feature from immutable startup config rather than runtime toggles.

When it happens

Trigger: Calling await pool.update_maint_notifications_config(MaintNotificationsConfig(enabled=False)) on a pool where maint_notifications_enabled() is already True.

Common situations: Runtime config reload that flips a feature flag off; generic enable/disable toggle code reused for the notifications feature; misunderstanding that enabling is irreversible on a given pool.

Related errors

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

Appendix: source

Thrown at redis/asyncio/connection.py:2051

    async def update_maint_notifications_config(
        self,
        maint_notifications_config: MaintNotificationsConfig,
        oss_cluster_maint_notifications_handler: (
            AsyncOSSMaintNotificationsHandler | None
        ) = None,
    ) -> None:
        """
        Updates the maintenance notifications configuration.
        This method should be called only if the pool was created
        without enabling the maintenance notifications and
        in a later point in time maintenance notifications
        are requested to be enabled.
        """
        if (
            self.maint_notifications_enabled()
            and not maint_notifications_config.enabled
        ):
            raise ValueError(
                "Cannot disable maintenance notifications after enabling them"
            )

        if oss_cluster_maint_notifications_handler:
            self._oss_cluster_maint_notifications_handler = (
                oss_cluster_maint_notifications_handler
            )
            # OSS cluster mode and pool-handler mode are mutually exclusive
            # (see __init__). A pool created with the default RESP3 "auto"
            # config wires a pool handler before this method runs; clear it so
            # new and existing connections are not configured with both handlers.
            self._maint_notifications_pool_handler = None
        else:
            if (
                maint_notifications_config.enabled
                and not self._maintenance_notifications_supported()
            ):
                if maint_notifications_config.enabled is True:

View on GitHub (pinned to 6a6b581b48)