{"record":{"id":"ad2272d5dfa23f8f","repo":"redis/redis-py","slug":"maintenance-notifications-are-not-supported-with-u","errorCode":null,"errorMessage":"Maintenance notifications are not supported with Unix domain socket connections","messagePattern":"Maintenance notifications are not supported with Unix domain socket connections","errorType":"exception","errorClass":"RedisError","httpStatus":null,"severity":"error","filePath":"redis/asyncio/client.py","lineNumber":422,"sourceCode":"                \"encoding_errors\": encoding_errors,\n                \"decode_responses\": decode_responses,\n                \"retry_on_error\": retry_on_error,\n                \"retry\": copy.deepcopy(retry),\n                \"max_connections\": max_connections,\n                \"health_check_interval\": health_check_interval,\n                \"client_name\": client_name,\n                \"driver_info\": computed_driver_info,\n                \"redis_connect_func\": redis_connect_func,\n                \"protocol\": protocol,\n                \"legacy_responses\": legacy_responses,\n            }\n            # based on input, setup appropriate connection args\n            if unix_socket_path is not None:\n                if (\n                    maint_notifications_config\n                    and maint_notifications_config.enabled is True\n                ):\n                    raise RedisError(\n                        \"Maintenance notifications are not supported with Unix \"\n                        \"domain socket connections\"\n                    )\n                kwargs.update(\n                    {\n                        \"path\": unix_socket_path,\n                        \"connection_class\": UnixDomainSocketConnection,\n                        \"maint_notifications_config\": MaintNotificationsConfig(\n                            enabled=False\n                        ),\n                    }\n                )\n            else:\n                # TCP specific options\n                kwargs.update(\n                    {\n                        \"host\": host,\n                        \"port\": port,","sourceCodeStart":404,"sourceCodeEnd":440,"githubUrl":"https://github.com/redis/redis-py/blob/6a6b581b48225afa0b76912d1028c6035baee932/redis/asyncio/client.py#L404-L440","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before\nfrom redis.maint_notifications import MaintNotificationsConfig\nr = redis.asyncio.Redis(\n    unix_socket_path='/var/run/redis/redis.sock',\n    maint_notifications_config=MaintNotificationsConfig(enabled=True),\n)  # -> RedisError: Maintenance notifications are not supported with Unix domain socket connections\n\n# after - choose one path\n# (a) keep UDS, drop maint notifications\nr = redis.asyncio.Redis(unix_socket_path='/var/run/redis/redis.sock')\n# (b) keep maint notifications, use TCP\nr = redis.asyncio.Redis(\n    host='redis', port=6379,\n    maint_notifications_config=MaintNotificationsConfig(enabled=True),\n)","handlingStrategy":"validation","validationCode":"def make_redis(unix_socket_path=None, maint=None, **kw):\n    import redis.asyncio as redis\n    if unix_socket_path and maint and getattr(maint, 'enabled', False):\n        raise ValueError('maintenance notifications need TCP; disabling for UDS')\n    return redis.Redis(\n        unix_socket_path=unix_socket_path, maint_notifications_config=maint, **kw\n    )","typeGuard":"from redis.exceptions import RedisError\n\ndef is_maint_uds_conflict(e: BaseException) -> bool:\n    return isinstance(e, RedisError) and 'unix domain socket' in str(e).lower()","tryCatchPattern":"from redis.exceptions import RedisError\ntry:\n    r = redis.asyncio.Redis(unix_socket_path=p, maint_notifications_config=cfg)\nexcept RedisError:\n    r = redis.asyncio.Redis(unix_socket_path=p)  # fall back without maint notifications","preventionTips":["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."],"tags":["config","async","init","unix-socket","maintenance-notifications"],"backgroundTag":null,"analyzedSha":"6a6b581b48225afa0b76912d1028c6035baee932","analyzedAt":"2026-08-10T12:52:44.840Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}