{"record":{"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":1917,"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":1899,"sourceCodeEnd":1935,"githubUrl":"https://github.com/redis/redis-py/blob/6a6b581b48225afa0b76912d1028c6035baee932/redis/asyncio/connection.py#L1899-L1935","documentation":"Raised as RedisError from the async maintenance-notifications pool mixin when maintenance notifications are explicitly enabled (config.enabled is True) but the connection is a Unix domain socket ('path' in connection_kwargs). UDS connections have no host endpoint to describe in CLIENT MAINT_NOTIFICATIONS, so the feature is unsupported. The check fires during pool construction, before any connect.","triggerScenarios":"Constructing an async client/pool from a unix:// URL with maint_notifications_config=MaintNotificationsConfig(enabled=True) (or a config object whose enabled is explicitly True). TCP/SSL paths take a different branch.","commonSituations":"Reusing a maintenance-notifications-enabled pool config across both TCP and UDS deployments; enabling the feature globally in a shared factory; testing locally over UDS with a config meant for production TCP.","solutions":["Disable maintenance notifications for UDS deployments: pass maint_notifications_config=None or MaintNotificationsConfig(enabled=False).","Switch the UDS connection to a TCP connection if you need maintenance notifications.","Make the factory conditionally enable the feature only when connection_class is TCP/SSL."],"exampleFix":"// before\npool = ConnectionPool.from_url('unix:///var/run/redis.sock', maint_notifications_config=MaintNotificationsConfig(enabled=True))\n// after\npool = ConnectionPool.from_url('unix:///var/run/redis.sock', maint_notifications_config=None)","handlingStrategy":"validation","validationCode":"def maint_config_for_uds(enabled: bool | None):\n    # UDS does not support maintenance notifications\n    return None if enabled else None","typeGuard":"from redis.exceptions import RedisError\n\ndef is_uds_maint_error(exc: BaseException) -> bool:\n    return isinstance(exc, RedisError) and 'Unix domain socket' in str(exc)","tryCatchPattern":"from redis.exceptions import RedisError\n\ntry:\n    pool = ConnectionPool.from_url('unix:///var/run/redis.sock', maint_notifications_config=cfg)\nexcept RedisError as e:\n    if 'Unix domain socket' in str(e):\n        pool = ConnectionPool.from_url('unix:///var/run/redis.sock')  # no maint\n    else:\n        raise","preventionTips":["Do not enable maintenance notifications on UDS pools.","Make config factories conditional on connection_class.","Document that maintenance notifications require TCP/SSL endpoints."],"tags":["maintenance-notifications","uds","config","validation","async","pool"],"backgroundTag":null,"analyzedSha":"6a6b581b48225afa0b76912d1028c6035baee932","analyzedAt":"2026-08-10T12:52:44.840Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-21T04:17:39.646Z"}