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 when update_maint_notifications_config() is called with a config whose 'enabled' flag is False while the pool already has maintenance notifications enabled. Maintenance notifications are designed as a one-way switch: once a pool is configured to receive them, the connections, parser hooks, and handlers are wired in and cannot be torn down by simply flipping the flag back off. To 'disable' you must recreate the pool/client without the maintenance-notifications config.

Source

Thrown at redis/asyncio/connection.py:2048

    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 da03cdc7e8)

Solutions

1. Recreate the Redis client / connection pool from scratch instead of trying to disable notifications on an existing one: disconnect() then construct a new Redis(...) without the maintenance-notifications config.
2. If you must call update_maint_notifications_config, ensure the MaintNotificationsConfig you pass has enabled=True (this path is enable-only).
3. Track your own 'enabled' state and short-circuit before calling the API when you intend to turn it off.

Example fix

// before
await pool.update_maint_notifications_config(
    MaintNotificationsConfig(enabled=False)
)
// after
await pool.disconnect()
redis = Redis.from_url(url)  # fresh pool, no maint-notifications config

async def safe_update_maint_config(pool, config):
    if not config.enabled and pool.maint_notifications_enabled():
        # one-way switch: do not call update with enabled=False
        return False
    await pool.update_maint_notifications_config(config)
    return True

def is_disable_attempt(pool, config) -> bool:
    return pool.maint_notifications_enabled() and not getattr(config, 'enabled', True)

try:
    await pool.update_maint_notifications_config(config)
except ValueError as e:
    if 'Cannot disable' in str(e):
        # recreate the pool instead
        ...

When it happens

Trigger: Calling ConnectionPool.update_maint_notifications_config(MaintNotificationsConfig(enabled=False)) (or Redis/RedisCluster.update_maint_notifications_config with enabled=False) on a pool where maint_notifications_enabled() already returns True. Also hit indirectly by clients that re-apply a config object with enabled defaulted to False during a reconfiguration step.

Common situations: Building a control plane that toggles maintenance notifications on/off at runtime; copying a config template whose 'enabled' defaults to False and passing it to the update API; misreading the docstring which only describes enabling, not disabling.

Related errors

• Maintenance notifications handlers on connection are only su
• Maintenance notifications are only supported with RESP versi
• Either maint_notifications_pool_handler or oss_cluster_maint
• "max_connections" must be a positive integer
• Argument 'db' must be 0 or None in cluster mode

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