Agent Troubleshooting

Solutions for common agent issues including connectivity, high CPU usage, and failed updates.

Agent Won't Connect

If the agent appears as "offline" in the dashboard after installation:

1. Check the service is running

Get-Service "MaxRMM Agent"

If the status is Stopped, start it:

Start-Service "MaxRMM Agent"

2. Check network connectivity

# Test WebSocket endpoint
Test-NetConnection -ComputerName agents.maxrmm.com -Port 443

# Test API endpoint
Invoke-WebRequest -Uri "https://api.maxrmm.com/health" -UseBasicParsing

If the connection fails, verify that outbound port 443 is open in your firewall and that no proxy is blocking WebSocket connections.

3. Check the agent log

Get-Content "C:\Program Files\MaxRMM\logs\agent.log" -Tail 50

Look for error messages such as:

• WebSocket connection failed — network or firewall issue
• Authentication failed — agent token is invalid; may need to reinstall
• TLS handshake error — outdated TLS version; ensure TLS 1.2+ is enabled

4. Ensure TLS 1.2 is enabled

The MaxRMM server requires TLS 1.2 or later. On older systems, you may need to enable it:

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

Agent Shows High CPU Usage

The agent should use less than 1% CPU during normal operation. If you see sustained high CPU:

1. Enable debug logging

Set-ItemProperty -Path "HKLM:\SOFTWARE\MaxRMM\Agent" -Name "LogLevel" -Value "debug" -Type String
Restart-Service "MaxRMM Agent"

2. Check the log for rapid reconnection loops

Get-Content "C:\Program Files\MaxRMM\logs\agent.log" -Tail 100 | Select-String "reconnect"

Rapid reconnection attempts can cause elevated CPU. This usually indicates a network issue where the WebSocket connection is being dropped and reestablished repeatedly.

3. Check for large WatchedServices lists

Monitoring a very large number of services (50+) can increase CPU overhead. Review your WatchedServices configuration and remove services you do not need to monitor.

4. Reset to defaults

Set-ItemProperty -Path "HKLM:\SOFTWARE\MaxRMM\Agent" -Name "ReportInterval" -Value 60 -Type DWord
Set-ItemProperty -Path "HKLM:\SOFTWARE\MaxRMM\Agent" -Name "LogLevel" -Value "info" -Type String
Restart-Service "MaxRMM Agent"

Log File Location

Agent logs are stored at:

C:\Program Files\MaxRMM\logs\agent.log

Archived logs follow the pattern agent-1.log, agent-2.log, etc. (up to 5 rotated files, 10 MB each).

To follow the log in real time:

Get-Content "C:\Program Files\MaxRMM\logs\agent.log" -Wait -Tail 20

Force Agent Update

The agent auto-updates when a new version is published. To force an immediate update:

From the dashboard

1. Go to Agents and select the agent
2. Click Commands → Force Update
3. The agent will download and install the latest version, then restart

From the endpoint

& "C:\Program Files\MaxRMM\maxrmm-agent.exe" --update

Rollback to Previous Version

If a new agent version causes issues, you can roll back:

# Stop the service
Stop-Service "MaxRMM Agent"

# The previous version is preserved as a backup
Copy-Item "C:\Program Files\MaxRMM\maxrmm-agent.exe.bak" "C:\Program Files\MaxRMM\maxrmm-agent.exe" -Force

# Start the service
Start-Service "MaxRMM Agent"

Agent Reinstallation

If all else fails, a clean reinstall resolves most issues:

# Uninstall
& "C:\Program Files\MaxRMM\maxrmm-agent.exe" --uninstall

# Wait a moment
Start-Sleep -Seconds 5

# Reinstall with a fresh key
powershell -ExecutionPolicy Bypass -Command "irm 'https://releases.maxrmm.com/install.ps1' | iex" -Key IK-your-key-here

The agent will register as a new device. The old agent entry in the dashboard can be deleted.

Common Error Messages