{"id":"a1324965a550d830","repo":"redis/redis-py","slug":"maintenance-notifications-are-not-supported-with-u-a13249","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/client.py","lineNumber":432,"sourceCode":"                \"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                \"credential_provider\": credential_provider,\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":414,"sourceCodeEnd":450,"githubUrl":"https://github.com/redis/redis-py/blob/da03cdc7e8731092b13e395605c3c1fb2de25de1/redis/client.py#L414-L450","documentation":"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.","triggerScenarios":"Constructing Redis(unix_socket_path=..., protocol=3, maint_notifications_config=MaintNotificationsConfig(enabled=True)).","commonSituations":"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).","solutions":["Disable maintenance notifications when connecting over a Unix socket: maint_notifications_config=MaintNotificationsConfig(enabled=False) or omit it.","Switch to a TCP connection if you need maintenance notifications.","Decouple the two config knobs so socket-path and maint-notifications are not both enabled."],"exampleFix":"# before\nr = Redis(unix_socket_path='/var/run/redis/redis.sock',\n         protocol=3,\n         maint_notifications_config=MaintNotificationsConfig(enabled=True))  # RedisError\n# after\nr = Redis(unix_socket_path='/var/run/redis/redis.sock',\n         protocol=3,\n         maint_notifications_config=MaintNotificationsConfig(enabled=False))","handlingStrategy":"validation","validationCode":"if unix_socket_path and maint_notifications_config and maint_notifications_config.enabled:\n    raise ConfigError('Disable maint notifications for Unix socket connections')","typeGuard":"def maint_enabled(cfg) -> bool:\n    return bool(cfg and getattr(cfg, 'enabled', False))","tryCatchPattern":"try:\n    r = Redis(unix_socket_path=path, maint_notifications_config=cfg)\nexcept RedisError as e:\n    logger.error('client construction failed: %s', e)\n    raise","preventionTips":["Never enable maint notifications over a Unix socket.","Keep socket-path and maint-notification config mutually exclusive."],"tags":["config","maintenance-notifications","unix-socket"],"analyzedSha":"da03cdc7e8731092b13e395605c3c1fb2de25de1","analyzedAt":"2026-08-04T20:26:47.563Z","schemaVersion":2}