redis/redis-py · error · RedisError

Maintenance notifications are not supported for connections

Error message

Maintenance notifications are not supported for connections without a host

What it means

Raised as a RedisError when maintenance notifications are explicitly enabled, the connection is not a Unix socket and uses a supported class, but there is no 'host' in connection_kwargs. CLIENT MAINT_NOTIFICATIONS identifies an endpoint by host, so a TCP-like connection without a host cannot be tracked. This is the fallthrough after the UDS and class checks at lines 1913/1921.

Source

Thrown at redis/asyncio/connection.py:1933

                            "Maintenance notifications are not supported for "
                            "Unix domain socket connections"
                        )

                    # Custom connection classes must inherit the async maintenance
                    # mixin so handlers can update connection state safely.
                    if not self._maintenance_notifications_connection_class_supported():
                        connection_class = getattr(self, "connection_class", None)
                        connection_class_name = getattr(
                            connection_class, "__name__", connection_class
                        )
                        raise RedisError(
                            "Maintenance notifications are not supported for "
                            f"connection class {connection_class_name}"
                        )

                    # TCP-like connections still need a host to identify the
                    # endpoint that can move during maintenance.
                    raise RedisError(
                        "Maintenance notifications are not supported for connections "
                        "without a host"
                    )
                self._maint_notifications_pool_handler = None
                self._oss_cluster_maint_notifications_handler = None
                return

            if not is_protocol_supported:
                raise RedisError(
                    "Maintenance notifications handlers on connection are only supported with RESP version 3"
                )

            if oss_cluster_maint_notifications_handler:
                self._oss_cluster_maint_notifications_handler = (
                    oss_cluster_maint_notifications_handler
                )
                self._update_connection_kwargs_for_maint_notifications(
                    oss_cluster_maint_notifications_handler=self._oss_cluster_maint_notifications_handler

View on GitHub (pinned to da03cdc7e8)

Solutions

Ensure connection_kwargs includes a valid 'host' (TCP endpoint).
Disable maintenance notifications if the connection has no host identity.
Use the standard Connection with host/port so the feature has an endpoint to register.

Example fix

// before
pool = ConnectionPool(connection_class=MyHostlessConn,
    maint_notifications_config=MaintNotificationsConfig(enabled=True))

// after
pool = ConnectionPool(host="redis.local", port=6379,
    maint_notifications_config=MaintNotificationsConfig(enabled=True))

Defensive patterns

Strategy: validation

Validate before calling

def maint_notifications_has_host(connection_kwargs: dict) -> bool:
    return bool(connection_kwargs.get("host")) and "path" not in connection_kwargs

Try / catch

from redis.exceptions import RedisError
try:
    pool = ConnectionPool(connection_kwargs=kwargs, maint_notifications_config=cfg)
except RedisError as e:
    if "without a host" in str(e):
        pool = ConnectionPool(host="redis.local", port=6379, maint_notifications_config=cfg)
    else:
        raise

Prevention

Ensure a 'host' is set when enabling maintenance notifications.
Use the standard Connection with host/port.
Don't strip host from connection_kwargs when customizing pools.

When it happens

Trigger: Constructing a pool with maint_notifications_config enabled=True where connection_kwargs omits 'host' (e.g. a custom connection class that does not set host, or a misconfigured pool). The check at line 1998 (_maintenance_notifications_supported) requires a truthy 'host'.

Common situations: A custom connection class that connects by some non-host identifier but is not a UDS; manually building a pool with connection kwargs that drop 'host'; enabling the feature on an abstract/incomplete configuration.

Related errors

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