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 ValueError by update_maint_notifications_config when maintenance notifications are currently enabled (maint_notifications_enabled() is True) and the caller passes a MaintNotificationsConfig with enabled=False. Disabling maintenance notifications at runtime is intentionally unsupported — once a pool is wired for them, connections and handlers are bound and cannot be cleanly torn down by a config flip.

Solutions

To 'disable', create a fresh pool/client without maintenance notifications instead of flipping the existing pool's config.
Only call update_maint_notifications_config with a config whose enabled is True (adjusting other fields), or to switch handler modes.
Design feature flags to recreate the client rather than mutate an enabled pool.

Example fix

# before
pool.update_maint_notifications_config(MaintNotificationsConfig(enabled=False))  # raises
# after - recreate the pool instead
new_pool = ConnectionPool(maint_notifications_config=MaintNotificationsConfig(enabled=False))

Defensive patterns

Strategy: validation

Validate before calling

def safe_update_maint_config(pool, new_cfg):
    if pool.maint_notifications_enabled() and not getattr(new_cfg, 'enabled', True):
        raise ValueError('Cannot disable maintenance notifications on an enabled pool; recreate it instead')
    pool.update_maint_notifications_config(new_cfg)

Try / catch

try:
    pool.update_maint_notifications_config(new_cfg)
except ValueError as e:
    if 'Cannot disable maintenance notifications' in str(e):
        pool = ConnectionPool(maint_notifications_config=new_cfg)  # recreate
    else:
        raise

Prevention

Never try to flip maintenance notifications off on an existing pool.
Design feature flags to recreate the client, not mutate the pool.
Only update other config fields on an enabled pool.

When it happens

Trigger: Calling pool.update_maint_notifications_config(MaintNotificationsConfig(enabled=False)) after the pool was created with maintenance notifications enabled (including the RESP3 default auto-enable).

Common situations: Toggling maintenance notifications off at runtime via a config update. Feature-flag flip that calls update_maint_notifications_config with a disabled config.

Related errors

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

Appendix: source

Thrown at redis/connection.py:2581

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