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 at construction of async Redis() when both unix_socket_path is set and maint_notifications_config.enabled is True. Maintenance notifications ride on a server-pushed mechanism that is only delivered over TCP-managed connections, so the combination is rejected up front rather than silently ignored. redis.exceptions.RedisError; fires at client.py:418-425 before any connection is made.

Source

Thrown at redis/asyncio/client.py:422

                "encoding_errors": encoding_errors,
                "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,
                "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)

Solutions

If you need maintenance notifications, use TCP (drop unix_socket_path) - the feature requires a TCP connection.
If you must use a Unix socket, don't enable maint notifications (omit the flag or set enabled=False; the client auto-disables it when enabled is left unset).
Build clients via a factory so a shared 'prod config' can't leak the maint-notifications toggle into a UDS instance.

Example fix

# before
from redis.maint_notifications import MaintNotificationsConfig
r = redis.asyncio.Redis(
    unix_socket_path='/var/run/redis/redis.sock',
    maint_notifications_config=MaintNotificationsConfig(enabled=True),
)  # -> RedisError: Maintenance notifications are not supported with Unix domain socket connections

# after - choose one path
# (a) keep UDS, drop maint notifications
r = redis.asyncio.Redis(unix_socket_path='/var/run/redis/redis.sock')
# (b) keep maint notifications, use TCP
r = redis.asyncio.Redis(
    host='redis', port=6379,
    maint_notifications_config=MaintNotificationsConfig(enabled=True),
)

Defensive patterns

Strategy: validation

Validate before calling

def make_redis(unix_socket_path=None, maint=None, **kw):
    import redis.asyncio as redis
    if unix_socket_path and maint and getattr(maint, 'enabled', False):
        raise ValueError('maintenance notifications need TCP; disabling for UDS')
    return redis.Redis(
        unix_socket_path=unix_socket_path, maint_notifications_config=maint, **kw
    )

Type guard

from redis.exceptions import RedisError

def is_maint_uds_conflict(e: BaseException) -> bool:
    return isinstance(e, RedisError) and 'unix domain socket' in str(e).lower()

Try / catch

from redis.exceptions import RedisError
try:
    r = redis.asyncio.Redis(unix_socket_path=p, maint_notifications_config=cfg)
except RedisError:
    r = redis.asyncio.Redis(unix_socket_path=p)  # fall back without maint notifications

Prevention

Maintenance notifications are TCP-only by design - don't enable them on UDS clients.
Build clients via a factory so shared 'prod config' can't leak the toggle into a UDS instance.
This fails at __init__, before any network call - validate config in tests/CI.

When it happens

Trigger: redis.asyncio.Redis(unix_socket_path='/var/run/redis/redis.sock', maint_notifications_config=MaintNotificationsConfig(enabled=True)). The constructor check trips at client.py:418-425.

Common situations: Enabling maintenance notifications globally (e.g. from a shared config loader) and then pointing one client at a UDS; copy-pasting a TCP config that has maint notifications into a UDS client; testing locally over UDS with a prod-style config.

Related errors

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