redis/redis-py · error · RedisError

Maintenance notifications are not supported with Unix…

Error message

Maintenance notifications are not supported with Unix domain socket connections

What it means

Raised as RedisError during Redis.__init__ when a Unix domain socket path is supplied AND maintenance notifications are enabled. Maintenance notifications rely on RESP3 out-of-band pushes delivered over TCP; Unix socket connections do not support this transport, so the combination is rejected up front. The constructor then forces maint_notifications_config.enabled = False for the socket connection.

Solutions

1. Disable maintenance notifications when using a unix socket: pass MaintNotificationsConfig(enabled=False) or omit it.
2. Switch to a TCP connection (host/port) if you need maintenance notifications.

Example fix

# before
r = Redis(unix_socket_path='/var/run/redis/redis.sock',
         maint_notifications_config=MaintNotificationsConfig(enabled=True))  # RedisError
# after
r = Redis(unix_socket_path='/var/run/redis/redis.sock',
         maint_notifications_config=MaintNotificationsConfig(enabled=False))

if unix_socket_path and maint_notifications_config and maint_notifications_config.enabled:
    raise ValueError("disable maintenance notifications for unix socket")

When it happens

Trigger: Constructing Redis(unix_socket_path='/path/sock', maint_notifications_config=MaintNotificationsConfig(enabled=True)). The check at client.py:428-435 fires before the connection pool is created.

Common situations: Running Redis locally via unix socket (common in sidecar/same-host setups) and copying a config that enables maintenance notifications intended for a TCP/cluster deployment. Enabling OSS cluster maintenance notifications without switching off unix sockets.

Related errors

• Maintenance notifications are only supported with RESP…
• Maintenance notifications handlers on connection are only…
• Maintenance notifications handlers on connection are only…
• Maintenance notifications handlers on connection are only…
• Cannot disable maintenance notifications after enabling them

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

Appendix: source

Thrown at redis/client.py:432

                "decode_responses": decode_responses,
                "retry_on_error": retry_on_error,
                "retry": copy.deepcopy(retry),
                "max_connections": max_connections,
                "health_check_interval": health_check_interval,
                "client_name": client_name,
                "driver_info": computed_driver_info,
                "redis_connect_func": redis_connect_func,
                "credential_provider": credential_provider,
                "protocol": protocol,
                "legacy_responses": legacy_responses,
            }
            # based on input, setup appropriate connection args
            if unix_socket_path is not None:
                if (
                    maint_notifications_config
                    and maint_notifications_config.enabled is True
                ):
                    raise RedisError(
                        "Maintenance notifications are not supported with Unix "
                        "domain socket connections"
                    )
                kwargs.update(
                    {
                        "path": unix_socket_path,
                        "connection_class": UnixDomainSocketConnection,
                        "maint_notifications_config": MaintNotificationsConfig(
                            enabled=False
                        ),
                    }
                )
            else:
                # TCP specific options
                kwargs.update(
                    {
                        "host": host,
                        "port": port,

View on GitHub (pinned to 6a6b581b48)