Endpoint Central Agent Installation Failure - Mac/Linux Troubleshooting Guide

Last Updated On: 27 Oct 2026|

7 minutes read |

Endpoint Central Agent Installation Failure - Mac/Linux Troubleshooting Guide

Problem

You are unable to install the Endpoint Central agent on computers running Mac/Linux operating systems.

Causes

Pre-requisite failures: SSH and SCP communication not enabled, network connectivity issues, invalid credentials, insufficient permissions.
Push failures: User lacks permission to access specific directories, target computer disconnected, insufficient disk space.

Resolution

1. Pre-requisites failure

Ensure SSH & SCP communication is enabled:

Linux: Use the command `systemctl status ssh` or `service ssh status` to check the service status. Refer to https://www.tecmint.com/install-openssh-server-in-linux/ for setup instructions.
Mac: Go to System Preferences > Sharing > Enable File Sharing and Remote Login.

Verify remote connectivity:

Ensure you can connect to the target computer using its machine name via SSH. If only the IP address works, reconfigure DNS resolution.
Verify the provided credentials match those in Endpoint Central server settings.
Ensure the specified user has root or sudo access.

Root user configuration (Linux):

Search for the file `/etc/ssh/sshd_config` in the Terminal.
Ensure `PermitRootLogin` is set to "yes" and `PasswordAuthentication` is set to "yes".

2. Push Failure

Verify user permissions:

Check for disconnection or insufficient disk space:

Ensure the target computer remains connected throughout the process.
Verify sufficient disk space on the target computer.

By following the steps for the corresponsing error remarks, you should be able to identify and resolve the issue preventing Endpoint Central Agent installation on your Mac/Linux computers.

Error Message

Description

Resolution

No Agent Available/Installed

Trying to uninstall a non-existent agent.

Ensure the agent is installed before uninstalling.

Agent up to date

Agent already has the latest version.

No action required.

AgentUpgrade Required

Lower version agent detected.

Upgrade will be automatic if communication allows, otherwise uninstall and reinstall manually.

Agent Need to uninstall & reinstalled

Mismatch between agent version and server details.

Uninstall and reinstall the agent manually. This resolution also applies to Windows agents when the agent version does not match the server details, for example, when the agent remains in the Pending approval status.

Unable to push installer files

Permission issues, unavailable path, or missing files.

Verify permissions and ensure /tmp is not mounted with "noexec" permission.

Install failed due to unknown reason

Unknown error during installation.

Refer to server logs for detailed information.

Root permission denied

Insufficient user permissions.

Configure a user with root or sudo access.

Uninstall failed due to unknown reason

Unknown error during uninstallation.

Refer to server logs for detailed information. For Linux agents, you can also check the agent logs available in /usr/local/manageengine/uems_agent/logs/ on the target computer.

Failed to establish connection

Target computer unreachable from the server.

Ensure the target computer is reachable.

Agent install fails if other probe managed agent encountered

Agent already managed by a different probe.

N/A (Agent cannot be managed by this probe).

Linux agent installation unknown architecture

Unsupported endpoint architecture.

Linux agent supports only x64 and x86 architectures. ARM-based Linux operating systems are not supported.

Unable to locate the agent directory for uninstallation

Agent not properly installed.

Ensure the agent is properly installed.

Agent Installation failed. Incorrect agent OS type error

Incorrect OS type chosen for installation/uninstallation.

Choose the correct OS type.

Server to Agent reachability issues

Various connection issues.

SSH Error	Description	Resolution
No such host	Server cannot locate/resolve the hostname.	Verify hostname accuracy.
Connection refused	Server cannot connect via SSH on port 22.	Ensure SSH service is running and port 22 is accessible.
Timeout	Connection attempt exceeded 30 seconds.	Improve network connectivity or troubleshoot slowness.

Agent endpoint authentication error

Invalid username/password provided.

Use the correct credentials.

Connection reset by peer

Displayed when you run the downloaded installer manually on the Linux computer, for example, sudo ./UEMS_LinuxAgent_x64.bin.

This is an OS or SSH level issue on the target Linux computer and is not caused by the Endpoint Central agent installer. Check the SSH and OS level logs of the target computer.

Agent already exists (macOS installer)

The macOS installer package, when run manually, reports that the agent already exists, though no installed agent is visible.

Uninstall the existing agent manually:

Open Finder and navigate to /Library/ManageEngine/UEMS_Agent/. Right-click Uninstaller.app, click Open and enter the administrator password.
Alternatively, run the following command in Terminal: /Library/ManageEngine/UEMS_Agent/Uninstaller.app/Contents/MacOS/Uninstaller -silent. If Agent Protection restricts the uninstallation, run the command with -cli-totp=<TOTP>.
If the /Library/ManageEngine/UEMS_Agent/ folder does not exist, log in as an administrator, open Terminal and navigate to /Library/DesktopCentral_Agent/uninstall. Run sudo chmod 744 uninstall.sh and then sudo ./uninstall.sh. This removes all the files except the logs.

If the problem still persists, you can contact Endpoint Central support with the below details

Error Screenshot
Target machine name where the installation failed
Server logs.