redis/redis-py · error · ValueError

Cannot enable maintenance notifications for connection objec

Error message

Cannot enable maintenance notifications for connection object that doesn't have a host attribute.

What it means

Raised by _enable_maintenance_notifications when the connection object has no 'host' attribute (getattr returns None). Maintenance notifications are host-based (they track a moving endpoint), so a connection with no resolvable host cannot register them. This most often surfaces with connection types that do not set a TCP host (e.g. a UnixDomainSocketConnection or a custom/mock connection). The exception is a ValueError thrown at connection setup time when maint_notifications_config is enabled.

Source

Thrown at redis/connection.py:639

        if (
            check_protocol_version(self.get_protocol(), 3)
            and self.maint_notifications_config
            and self.maint_notifications_config.enabled
            and self._maint_notifications_connection_handler
            and host is not None
        ):
            self._enable_maintenance_notifications(
                maint_notifications_config=self.maint_notifications_config,
                check_health=check_health,
            )

    def _enable_maintenance_notifications(
        self, maint_notifications_config: MaintNotificationsConfig, check_health=True
    ):
        try:
            host = getattr(self, "host", None)
            if host is None:
                raise ValueError(
                    "Cannot enable maintenance notifications for connection"
                    " object that doesn't have a host attribute."
                )
            else:
                endpoint_type = maint_notifications_config.get_endpoint_type(host, self)
                self.send_command(
                    "CLIENT",
                    "MAINT_NOTIFICATIONS",
                    "ON",
                    "moving-endpoint-type",
                    endpoint_type.value,
                    check_health=check_health,
                )
                response = self.read_response()
                if not response or str_if_bytes(response) != "OK":
                    raise ResponseError(
                        "The server doesn't support maintenance notifications"
                    )

View on GitHub (pinned to da03cdc7e8)

Solutions

Disable maintenance notifications (do not enable maint_notifications_config) for non-TCP / Unix socket connections.
Use a TCP connection (Redis(host=...)) if you need maintenance notifications.
If using a custom Connection subclass, ensure it exposes a valid 'host' attribute before enabling maint notifications.

Example fix

// before
client = redis.Redis(unix_socket_path='/tmp/redis.sock', maint_notifications_config=cfg)
client.ping()
// after
client = redis.Redis(unix_socket_path='/tmp/redis.sock')  # maint notifications off for UDS

Defensive patterns

Strategy: validation

Validate before calling

from redis.connection import Connection
if getattr(conn, 'host', None) is None:
    raise ValueError('Connection has no host; disable maint_notifications_config for this connection type')
conn.connect()

Type guard

def supports_maint_notifications_by_host(conn) -> bool:
    return getattr(conn, 'host', None) is not None

Try / catch

try:
    client.ping()
except ValueError as e:
    if 'host attribute' in str(e):
        # disable maintenance notifications and retry
        pass

Prevention

Do not enable maint_notifications_config on UnixDomainSocketConnection or other non-host connection types.
Verify a connection exposes 'host' before enabling maintenance notifications.

When it happens

Trigger: Calling connect() on a connection that has maint_notifications_config.enabled set, where self.host is None. This includes UnixDomainSocketConnection (uses a path, not a host) or any Connection subclass that overrides/removes the host attribute while maintenance notifications are enabled via the client config.

Common situations: Configuring a client over a Unix domain socket (unix_socket_path) while maintenance notifications are turned on; passing a maint_notifications_config to a connection type that does not expose host; unit tests using mock/fake connections without setting host.

Related errors

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