{"id":"13e282b9663382d8","repo":"redis/redis-py","slug":"maintenance-notifications-are-not-supported-for-un","errorCode":null,"errorMessage":"Maintenance notifications are not supported for Unix domain socket connections","messagePattern":"Maintenance notifications are not supported for Unix domain socket connections","errorType":"exception","errorClass":"RedisError","httpStatus":null,"severity":"error","filePath":"redis/asyncio/connection.py","lineNumber":1914,"sourceCode":"    ) -> None:\n        protocol = kwargs.get(\"protocol\")\n        is_protocol_supported = check_protocol_version(protocol, 3)\n        is_connection_supported = self._maintenance_notifications_supported()\n\n        if (\n            maint_notifications_config is None\n            and is_protocol_supported\n            and is_connection_supported\n        ):\n            maint_notifications_config = MaintNotificationsConfig()\n\n        if maint_notifications_config and maint_notifications_config.enabled:\n            if not is_connection_supported:\n                if maint_notifications_config.enabled is True:\n                    # Unix sockets do not have a host endpoint for CLIENT\n                    # MAINT_NOTIFICATIONS to describe.\n                    if \"path\" in self.connection_kwargs:\n                        raise RedisError(\n                            \"Maintenance notifications are not supported for \"\n                            \"Unix domain socket connections\"\n                        )\n\n                    # Custom connection classes must inherit the async maintenance\n                    # mixin so handlers can update connection state safely.\n                    if not self._maintenance_notifications_connection_class_supported():\n                        connection_class = getattr(self, \"connection_class\", None)\n                        connection_class_name = getattr(\n                            connection_class, \"__name__\", connection_class\n                        )\n                        raise RedisError(\n                            \"Maintenance notifications are not supported for \"\n                            f\"connection class {connection_class_name}\"\n                        )\n\n                    # TCP-like connections still need a host to identify the\n                    # endpoint that can move during maintenance.","sourceCodeStart":1896,"sourceCodeEnd":1932,"githubUrl":"https://github.com/redis/redis-py/blob/da03cdc7e8731092b13e395605c3c1fb2de25de1/redis/asyncio/connection.py#L1896-L1932","documentation":"Raised as a RedisError during connection-pool initialization when maintenance notifications are explicitly enabled but the connection uses a Unix domain socket ('path' in connection_kwargs). CLIENT MAINT_NOTIFICATIONS needs a host:port endpoint to describe, so UDS connections are unsupported. Only fires when maint_notifications_config.enabled is True (explicit opt-in).","triggerScenarios":"Constructing a pool/client with connection_class=UnixDomainSocketConnection (or unix:// URL) together with maint_notifications_config=MaintNotificationsConfig(enabled=True) or an oss_cluster_maint_notifications_handler. The check at line 1913 detects 'path' in connection_kwargs.","commonSituations":"Enabling the maintenance-notifications feature against a UDS deployment; copying a cluster config (which sets up OSS maint notifications) onto a unix-socket client; explicitly enabling the feature when auto-detection would otherwise silently disable it.","solutions":["Disable maintenance notifications for UDS clients: omit maint_notifications_config or set enabled=False (the default).","Switch the connection to a TCP (host:port) endpoint if you genuinely need maintenance notifications.","Do not pass an oss_cluster_maint_notifications_handler when using unix://."],"exampleFix":"// before\nr = redis.asyncio.Redis(unix_socket_path=\"/var/run/redis/redis.sock\",\n    maint_notifications_config=MaintNotificationsConfig(enabled=True))\n\n// after\nr = redis.asyncio.Redis(unix_socket_path=\"/var/run/redis/redis.sock\")","handlingStrategy":"validation","validationCode":"def maint_notifications_compatible(connection_kwargs: dict) -> bool:\n    return \"path\" not in connection_kwargs  # UDS unsupported","typeGuard":null,"tryCatchPattern":"from redis.exceptions import RedisError\ntry:\n    r = redis.asyncio.Redis(unix_socket_path=p, maint_notifications_config=cfg)\nexcept RedisError as e:\n    if \"Unix domain socket\" in str(e):\n        r = redis.asyncio.Redis(unix_socket_path=p)  # drop maint notifications\n    else:\n        raise","preventionTips":["Don't enable maintenance notifications on UDS clients.","Let the library auto-disable the feature rather than forcing enabled=True.","Use TCP if you need maintenance notifications."],"tags":["maintenance-notifications","config","unix-socket","async"],"analyzedSha":"da03cdc7e8731092b13e395605c3c1fb2de25de1","analyzedAt":"2026-08-04T20:26:47.563Z","schemaVersion":2}