redis/redis-py · error · ValueError

Cannot disable maintenance notifications after enabling them

Error message

Cannot disable maintenance notifications after enabling them

What it means

Raised as a ValueError by update_maint_notifications_config (connection.py:2562-2568) when maintenance notifications are currently enabled (maint_notifications_enabled() is True) and you pass a new MaintNotificationsConfig with enabled=False. The library treats enabling as a one-way operation on an existing pool; it will not tear down already-configured handlers/connections.

Source

Thrown at redis/connection.py:2566

    def update_maint_notifications_config(
        self,
        maint_notifications_config: MaintNotificationsConfig,
        oss_cluster_maint_notifications_handler: Optional[
            OSSMaintNotificationsHandler
        ] = 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:
            # first update pool settings
            if self._oss_cluster_maint_notifications_handler:
                # Pool already in OSS cluster mode; update the OSS handler config
                # instead of creating a mutually-exclusive pool handler (which
                # would be silently ignored because the OSS handler wins priority
                # in both update helpers below).

View on GitHub (pinned to da03cdc7e8)

Solutions

1. Do not attempt to disable notifications on an already-enabled pool — create a new pool (without notifications) and switch clients to it instead.
2. If you need on/off toggling, design your app to recreate the pool/connection rather than mutate the existing one.
3. Guard the update call: only invoke update_maint_notifications_config when the desired enabled state differs AND you are enabling, not disabling.

Example fix

# before
pool.update_maint_notifications_config(
    MaintNotificationsConfig(enabled=False))  # raises if currently enabled

# after: recreate the pool without notifications instead
pool.disconnect()
client.set_pool(redis.ConnectionPool(
    protocol=3,
    maint_notifications_config=MaintNotificationsConfig(enabled=False)))

if new_cfg.enabled is False and pool.maint_notifications_enabled():
    raise ValueError("Cannot disable notifications on an enabled pool; recreate the pool instead.")

pool.update_maint_notifications_config(new_cfg)

def can_update_maint_config(pool, new_enabled: bool) -> bool:
    return not (pool.maint_notifications_enabled() and new_enabled is False)

try:
    pool.update_maint_notifications_config(new_cfg)
except ValueError as e:
    if "Cannot disable" in str(e):
        # recreate pool instead of mutating
        pool.disconnect()
        pool = redis.ConnectionPool(protocol=3, maint_notifications_config=new_cfg)
    else:
        raise

When it happens

Trigger: Calling pool.update_maint_notifications_config(MaintNotificationsConfig(enabled=False)) on a pool that was created with notifications enabled (or previously updated to enabled). This is an explicit reconfiguration call, not the constructor.

Common situations: Dynamic config toggles that flip notifications on/off at runtime; reusing a long-lived pool and trying to disable notifications during a maintenance window or shutdown; config-driven code that re-applies a 'disabled' config unconditionally.

Related errors

• Maintenance notifications handlers on connection are only su
• Either maint_notifications_pool_handler or oss_cluster_maint
• Maintenance notifications are not supported with {connection
• Maintenance notifications handlers on connection are only su
• Maintenance notifications are only supported with RESP versi

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