redis/redis-py · error · ValueError

Either maint_notifications_pool_handler or…

Error message

Either maint_notifications_pool_handler or oss_cluster_maint_notifications_handler must be set

What it means

Raised as ValueError inside _update_maint_notifications_configs_for_connections (the loop over _get_free_connections) when maintenance notifications are considered enabled but neither maint_notifications_pool_handler nor oss_cluster_maint_notifications_handler is provided to the method. This is an internal invariant of the pool: the public update_maint_notifications_config always supplies one handler, so reaching this branch implies a programming error inside the library or a subclass that overrides the update helpers incorrectly.

Solutions

Do not call _update_maint_notifications_configs_for_connections directly; use update_maint_notifications_config, which always supplies a handler.
If you subclass the pool, preserve the invariant that exactly one handler is non-None whenever maintenance notifications are enabled.
Report a bug if this surfaces from unmodified library code.

Defensive patterns

Strategy: try-catch

Validate before calling

# Internal invariant: do not call _update_maint_notifications_configs_for_connections directly.
# Always ensure a handler is present before updating:
if pool.maint_notifications_enabled():
    assert pool._maint_notifications_pool_handler or pool._oss_cluster_maint_notifications_handler
pool.update_maint_notifications_config(cfg)

Try / catch

try:
    pool.update_maint_notifications_config(cfg)
except ValueError as e:
    if 'must be set' in str(e):
        # internal invariant broken; recreate the pool
        pool = ConnectionPool(maint_notifications_config=cfg)
    else:
        raise

Prevention

Use the public update API rather than internal helpers.
If subclassing, preserve the one-handler invariant.
Report library bugs that surface this from unmodified code.

When it happens

Trigger: Calling _update_maint_notifications_configs_for_connections directly with both handler arguments None, or a subclass of the pool that overrides maint_notifications_enabled/_update_maint_notifications_configs_for_connections such that the invariant breaks.

Common situations: Subclassing the maintenance-notifications pool and breaking the handler contract. Library-internal logic error. Very unlikely from normal client usage.

Related errors

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

Appendix: source

Thrown at redis/connection.py:2699

        with self._get_pool_lock():
            for conn in self._get_free_connections():
                if oss_cluster_maint_notifications_handler:
                    # set cluster handler for conn
                    conn.set_maint_notifications_cluster_handler_for_connection(
                        oss_cluster_maint_notifications_handler
                    )
                    conn.maint_notifications_config = (
                        oss_cluster_maint_notifications_handler.config
                    )
                elif maint_notifications_pool_handler:
                    conn.set_maint_notifications_pool_handler_for_connection(
                        maint_notifications_pool_handler
                    )
                    conn.maint_notifications_config = (
                        maint_notifications_pool_handler.config
                    )
                else:
                    raise ValueError(
                        "Either maint_notifications_pool_handler or oss_cluster_maint_notifications_handler must be set"
                    )
                conn.disconnect()
            for conn in self._get_in_use_connections():
                if oss_cluster_maint_notifications_handler:
                    # Use set_maint_notifications_cluster_handler_for_connection
                    # (not _configure_maintenance_notifications) so the parser is
                    # obtained from the connection itself. _configure_* requires a
                    # parser argument and would raise here; it would also reset the
                    # connection's orig_* settings, which is wrong for an in-use
                    # (active) connection. This mirrors the idle-connection branch
                    # above and the pool-handler branches.
                    conn.set_maint_notifications_cluster_handler_for_connection(
                        oss_cluster_maint_notifications_handler
                    )
                    conn.maint_notifications_config = (
                        oss_cluster_maint_notifications_handler.config
                    )

View on GitHub (pinned to 6a6b581b48)