Agent Troubleshooting Tool
DEX Manager Plus works on the principle of agent server communication, where the agents residing on end-user machines, contact the central server once every 90 minutes as per the agent refresh policy. In addition, the agents will contact the central server during device startup and user login instances. The agent troubleshooting tool supported by DEX Manager Plus allows end-users to troubleshoot the agents and restore connection rather than requesting their IT administrators to look into the issue. Once the troubleshooting process completes, the tool generates a detailed report showing what failed and the recommended fix.
Understanding the need for troubleshooting agents
The DEX Manager Plus agent might go down due to network level issues or issues that breaks the agent service. IT administrators can view the live status of the managed agents under the Scope of Management view. When an agent is marked "down" (indicated with red color monitor icon), IT administrators can remotely connect to those endpoints and troubleshoot it. Likewise, end-users can check the status of their agent by accessing the tray icon. Whenever the agent icon is down, end-users can access this tool and troubleshoot their agent. Once the troubleshooting process is done, the tool will provide a detailed report on the agent communication issues and the fix.
How do I run the Agent Troubleshooting Tool?
Two methods are available on Windows — via the tray icon (recommended for end-users) or directly via the file path (for remote or command-line use).
Method 1 — Agent Tray Icon
- Locate the DEX Manager Plus agent icon in the Windows system tray (bottom-right taskbar).
- Right-click the icon and select Agent Troubleshoot > Troubleshoot.
- A new window opens. Click Start Troubleshooting to begin the diagnostic scan.
- View the results. Click any component for detailed status and linked KB articles.
Method 2 — Command Line / Direct File Path
Navigate to the agent installation directory and run the executable directly:
C:\Program Files (x86)\ManageEngine\UEMS_Agent\bin\agent_troubleshooting_tool.exeIf you run the troubleshooting tool, the output will appear like this one shown in the below image:-
- The troubleshooting tool scans once every 24 hours and caches the result. To fetch a fresh scan, click Scan Again inside the tool.
- The above image consists of an agent that is directly managed by the central server (OP) without a distribution server.
What does the tool check — and how do I read the output?
The troubleshooting action diagnoses primary network-level issues and displays the results graphically. Each component shows one of three states: Pass (healthy), Warning (potential issue — click for details), or Error (failed — click for the KB article with resolution steps). Here is a list of components checked:
- Agent Binaries
- Agent Identity
- Agent Service
- Antivirus
- Active Directory Connection Status
- Distribution Server Connection Status
- Notification Server Connection Status
- DEX Manager Plus Server Connection Status
- WMI Connection Status
- RDS Connectivity
How do I act on the results?
Click the component showing a warning or error. This expands the detailed status and links directly to the KB article for that specific issue. Follow the KB steps to resolve it, then click Scan Again to confirm the component is now healthy. If the issue persists, use Export to package all diagnostic data and contact ManageEngine Support.
Components in detail
- Agent Service: Displays the status of the Agent service, showing if it is running or not. If a warning or error message appears, clicking on the service provides access to attached KB articles for issue resolution.
Agent Identity: Displays details about the agent machine name, OS Name, Last bootup time, OS install date, Identifying number, and UUID. An error indication occurs if the agent machine was imaged from another machine and has not fully recovered.
Agent Binaries: Verifies successful extraction of agent binaries during installation and upgrade. Warning/error flags indicate unsuccessful extraction. (Example: Sample binaries like Software Metering Report, USB Report, Notification Server Client, Inventory Management, Patch Management)
WMI Connection Status: Windows Management Instrumentation (WMI) consists of specifications from Microsoft designed to streamline device and application management across a network of Windows computing systems. When the agent fails to retrieve WMI details from Windows, it triggers an error. This failure hampers Helpdesk requests, preventing their transmission to the server and impeding the functionality of UUID details and related functions.
Active Directory Connection Status: Displays the result of the Active Directory connection, providing domain and group details to which the machine and user are joined. In case the Active Directory connection fails, domain details cannot be updated, and patches and configurations related to the domain will not occur.
Antivirus: Lists installed Antivirus software and their associated GUIDs (Globally Unique Identifiers).
DEX Manager Plus Server Connection: Displays the connection status between the agent and server, automatically checking ping and port connection with server address. It showcases all addresses used by the agent to contact the server. Server-related issues are highlighted in the error column, with reconnection steps mentioned in the attached KB articles.
For DEX Manager Plus Cloud, the troubleshooting tool will display the agent's connection with the server through all cloud addresses. As the Cloud does not have a Notification server component, all agent-to-server refresh and on-demand functions occur via the cloud addresses.
- Distribution Server: Verifies the Agent-to-Distribution Server connection using ping and port connections. When the agent operates under the Distribution Server, all agent configurations, patch deployments and upgrades occur through the Distribution Server. It automatically validates the ping and port connection with the Distribution Server address. Any server-related issues will be displayed in the error column with reconnection steps in the attached KB article.
- Notification Server Connection: The Notification Server manages all on-demand actions executed by on-premise agents — remote connections, on-demand configurations, and patch deployments. The notification server necessitates a 10-minute idle connection for live status updates. Any connection issues are updated in the remarks column. To verify the 10-minute idle connection, click Start in the Notification Server Summary.
- RDS Connectivity: Verifies whether the agent can establish Remote Desktop Service (RDS) sessions with the server successfully.
Troubleshooting Summary
The Troubleshooting Summary provides detailed information on system details, agent-specific details such as version and installed location, firewall configurations, and the connection status of all agent components.
Where are the agent logs — and how do I share them with support?
Agent logs are accessible directly inside the tool via View Logs, segregated by component (system information, configuration, patch, and others). Log files are stored at:
C:\Program Files (x86)\ManageEngine\UEMS_Agent\logs\
If the KB articles linked inside the tool do not resolve the issue, click Export to package all troubleshooting data into a single report and share it with ManageEngine Support.
For version 11.4.2544.01.M and above, the troubleshooting tool will be available in the macOS agent.
- Navigate to the agent tray icon in the menu bar and select Tray Icon > Troubleshoot > Run troubleshooting tool.
- Alternatively, open Terminal and run:
/Library/ManageEngine/UEMS_Agent/bin/troubleshoot
- To view available options, run
troubleshoot --helpin Terminal.
What does the tool check on macOS?
Server connectivity details:
- Connection status with the main DEX Manager Plus server
- Connection status with the Distribution Server (if the agent is managed under a remote office with a DS)
- On-demand functionality to verify if the agent can receive and execute on-demand actions from the server
Service and Process Details:
- Checks whether all services required for the agent to function are running properly
- Reports any services that are inactive or have failed
Agent and Server Information:
- Agent version and installation directory
- Server address and communication details
- MDM enrollment status and MDM server address (if the machine is enrolled in MDM)
Where are the agent logs — and how do I share them with support?
Log files are stored at: /Library/ManageEngine/UEMS_Agent/logs/
To generate a detailed support dump, run: troubleshoot --dump
The dump is saved to: /Library/ManageEngine/UEMS_Agent/logs/UserLogs/dumps/
How do I verify agent connectivity to the server manually?
If you wish to verify the agent—server connection without running the full tool, use the following steps:
To check if the necessary ports are open:
- A blank screen indicates a successful connection. The same steps are applicable to check the Agent-DS connection as well.
telnet <Server Address> <Server Port>To check data transfer:
- Open the DEX Manager Plus server console in a browser from the agent machine. If the console fails to load, a firewall or network restriction is blocking the data transfer channel between agent and server.
To test file downloads from the agent machine:
- If a .xml file is displayed and available for download, it denotes a successful connection.
https://<Server_Address>:<Server_Port>/client-data/ns-status-details.xml