redis/redis-py · error · RedisError

Maintenance notifications are not supported with Unix domain

Error message

Maintenance notifications are not supported with Unix domain socket connections

What it means

Raised as RedisError in Redis.__init__ (redis/client.py:432) when a unix_socket_path is supplied together with a maint_notifications_config that has enabled=True. Maintenance notifications are delivered as server-pushed messages over RESP3, which requires a TCP connection; Unix domain sockets are incompatible, so the client refuses to construct.

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 da03cdc7e8)

Solutions

1. Disable maintenance notifications when connecting over a Unix socket: maint_notifications_config=MaintNotificationsConfig(enabled=False) or omit it.
2. Switch to a TCP connection if you need maintenance notifications.
3. Decouple the two config knobs so socket-path and maint-notifications are not both enabled.

Example fix

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

if unix_socket_path and maint_notifications_config and maint_notifications_config.enabled:
    raise ConfigError('Disable maint notifications for Unix socket connections')

def maint_enabled(cfg) -> bool:
    return bool(cfg and getattr(cfg, 'enabled', False))

try:
    r = Redis(unix_socket_path=path, maint_notifications_config=cfg)
except RedisError as e:
    logger.error('client construction failed: %s', e)
    raise

When it happens

Trigger: Constructing Redis(unix_socket_path=..., protocol=3, maint_notifications_config=MaintNotificationsConfig(enabled=True)).

Common situations: Reusing a config template that enables maintenance notifications then switching the path to a Unix socket; sidecar/local Redis via UDS but wanting maint notifications (unsupported combo).

Related errors

• Maintenance notifications are not supported for Unix domain
• Maintenance notifications are only supported with hiredis an
• Maintenance notifications are not supported for connection c
• Maintenance notifications are not supported for connections
• Maintenance notifications handlers on connection are only su

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