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 RedisError from the maintenance-notifications pool mixin when notifications are explicitly enabled and the connection is supported (not UDS, supported class) but the connection_kwargs lack a 'host'. The feature needs a host to identify the endpoint that can move during maintenance; without one (e.g. a connection class that does not record host) the configuration is rejected.

Solutions

  1. Pass host=<value> explicitly in connection_kwargs so the endpoint can be identified.
  2. If your connection genuinely has no host, disable maintenance notifications.
  3. Ensure custom connection classes propagate host into the kwargs the pool sees.

Example fix

// before
pool = ConnectionPool(connection_class=TCPConn, port=6379, maint_notifications_config=MaintNotificationsConfig(enabled=True))
// after
pool = ConnectionPool(connection_class=TCPConn, host='redis.local', port=6379, maint_notifications_config=MaintNotificationsConfig(enabled=True))
Defensive patterns

Strategy: validation

Validate before calling

def kwargs_have_host(connection_kwargs: dict) -> bool:
    return bool(connection_kwargs.get('host'))

Type guard

from redis.exceptions import RedisError

def is_no_host_maint_error(exc: BaseException) -> bool:
    return isinstance(exc, RedisError) and 'without a host' in str(exc).lower()

Try / catch

from redis.exceptions import RedisError

try:
    pool = ConnectionPool(connection_class=cls, **kw, maint_notifications_config=cfg)
except RedisError as e:
    if 'without a host' in str(e):
        kw.setdefault('host', default_host)
        pool = ConnectionPool(connection_class=cls, **kw, maint_notifications_config=cfg)
    else:
        raise

Prevention

When it happens

Trigger: Constructing a pool with maint_notifications_config.enabled=True where connection_kwargs has no 'host' key (a TCP-like class that was instantiated without host, or a custom class that does not propagate host into kwargs). This is the fallthrough branch after the UDS and class checks.

Common situations: Custom connection that accepts a non-host address form (e.g. abstract socket, dialer URI) but is not classified as UDS; misconfigured factory that strips host from kwargs; enabling the feature on a pool whose connection was built from positional args without host.

Related errors

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

Appendix: source

Thrown at redis/asyncio/connection.py:1936

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