Skip to main content

Troubleshooting

Common issues and resolutions for The One RMM agent installation, enrollment, patching, and remote execution.

Device Not Appearing in Console​

Symptom: You installed the agent but the device hasn't appeared in the Devices list after 5+ minutes.

Causes and resolutions:

  1. Firewall blocking outbound port 443 The agent connects to api.theonermm.app over HTTPS (port 443). If a host-based or network firewall blocks this, enrollment fails silently.

    • Verify connectivity: from the device run curl -I https://api.theonermm.app/health
    • Expected: HTTP 200. If it times out or returns a connection error, add a firewall rule allowing outbound TCP 443 to api.theonermm.app.

  2. Enrollment token expired Installer downloads are valid for 30 days. After expiry, new enrollments are rejected.

    • Navigate to Settings → Enrollment Tokens in the RMM console.
    • Regenerate the token and re-download the installer.

  3. Agent service not running

    • Windows: Open Services (services.msc) and confirm TheOneRMMAgent is Running. 
      sc query TheOneRMMAgent
    • macOS/Linux: 
      sudo systemctl status theonermm-agent
    • If stopped, start it manually: Start-Service TheOneRMMAgent (Windows) or sudo systemctl start theonermm-agent (Linux).

  4. Proxy blocking the connection If the device routes internet traffic through a proxy, configure the proxy settings in the agent:

    # Windows registry
    reg add "HKLM\SOFTWARE\TheOneRMM\Agent" /v ProxyUrl /t REG_SZ /d "http://proxy:3128"

    Restart the agent after making this change.

Device Shows Offline But Is Actually Online​

Symptom: The device is reachable on the network and appears to be running, but the RMM console shows it as Offline.

Causes and resolutions:

  1. Agent service stopped The agent process may have crashed or been stopped.

    • Restart the agent (see above).
    • Check the agent log for crash details: C:\ProgramData\TheOneRMM\logs\agent.log (Windows) or /var/log/theonermm/agent.log (Linux).

  2. Agent certificate expired The agent uses a TLS client certificate for authentication. Certificates are valid for 90 days and should auto-renew, but renewal can fail if the device was offline for an extended period.

    • Re-enroll the device: uninstall and reinstall the agent with a fresh token.
    • The device's history is preserved if hardware fingerprint matches.

  3. System clock skew JWT tokens are time-sensitive. If the device clock is significantly out of sync (> 5 minutes), authentication fails.

    • Enable automatic time sync (NTP) on the device: 
      # Windows
      w32tm /resync
      # Linux
      sudo timedatectl set-ntp true

Patch Deployment Failing​

Symptom: A patch deployment shows status Failed on some or all devices.

Causes and resolutions:

  1. Windows Update service disabled Patch deployment requires the Windows Update service (wuauserv) to be running.

    Get-Service wuauserv | Select-Object Status
    # If stopped:
    Set-Service wuauserv -StartupType Automatic
    Start-Service wuauserv

  2. Proxy blocking Windows Update endpoints Group Policy or a third-party tool may be redirecting Windows Update traffic. Check:

    reg query "HKLM\SOFTWARE\Policies\Microsoft\Windows\WindowsUpdate" /v WUServer

    If this returns a custom WSUS URL, ensure the WSUS server has the required patches.

  3. WSUS approvals missing If WSUS is in use, patches must also be approved in WSUS before the agent can install them. Approve the patches in your WSUS console, then retry the RMM deployment.

  4. Insufficient disk space Patch downloads require free space on the system drive. Ensure at least 2 GB free before deploying large patch sets.

Remote Command Timing Out​

Symptom: A remote command shows status timed_out before completing.

Causes and resolutions:

  1. Command generates very large output Commands that produce more than ~1 MB of output per second may trigger the 300-second timeout before completing.

    • Pipe output to a file on the device and retrieve the file via a second command or file transfer.
    • Reduce output verbosity: add -ErrorAction SilentlyContinue or pipe to Out-Null for non-critical output.

  2. Slow endpoint An overloaded device may execute commands slowly.

    • Increase the timeout for the specific job (up to 3600 seconds): set Timeout when creating the command.

  3. Command requires interactive input Commands that block waiting for user input will hang until timeout. Always use non-interactive flags:

    # Instead of: Install-Package foo
    Install-Package foo -Confirm:$false -Force

Alert Firing Continuously for Same Issue​

Symptom: The same alert fires repeatedly every few minutes for an issue that is not changing.

Causes and resolutions:

  1. Alert flapping — no alert suppression Enable alert suppression on the rule to prevent re-firing within a cooldown window:

    • Open the alert rule → Advanced Settings → Cooldown Period.
    • Set to 30 minutes. The alert will not re-fire within this window even if the condition remains true.

  2. Alert grouping not enabled If many devices are triggering the same rule, enable Alert Grouping to consolidate them.

  3. Underlying condition is actually flapping The metric is oscillating around the threshold (e.g., CPU 89% → 91% → 89%). Increase the Duration on the alert rule so it only fires if the condition is sustained, not momentary.

Performance Graphs Showing Gaps​

Symptom: Device performance charts show flat lines or "no data" periods.

Cause and resolution:

Gaps in performance graphs indicate the agent was offline during that period (device powered off, rebooted, or network disconnected). This is expected behavior — data cannot be backfilled.

To distinguish between "device was off" and "agent had an issue":

  • Check device uptime in the Properties tab.
  • Check agent log for error entries around the gap period.

macOS Agent Not Enrolling​

Symptom: The macOS installer runs but the device does not appear in the console, or a Gatekeeper warning appears.

Causes and resolutions:

  1. Gatekeeper blocking unsigned binary

    • Open System Settings → Privacy & Security.
    • Scroll to the security section and click Open Anyway next to the blocked item.
    • For automated MDM deployments, push a Gatekeeper exception profile (PPPC profile) via Jamf or Intune before deploying the installer.

  2. MDM profile needed for System Extension (Defend module) If the Defend module is active on macOS, it requires a System Extension approval via MDM:

    • Push a System Extension Policy profile that allows the Team ID for TheOneRMM.
    • Without this, the Defend module falls back to reduced telemetry collection.

  3. macOS Privacy & Security — Full Disk Access For complete monitoring of Application events and file access, the agent needs Full Disk Access:

    • Open System Settings → Privacy & Security → Full Disk Access.
    • Enable access for TheOneRMMAgent.
    • For MDM: push a Privacy Preferences Policy Control (PPPC) payload.

Linux Agent Install Failing​

Symptom: dpkg -i or rpm -i returns an error.

Causes and resolutions:

  1. Missing dependency

    # Debian/Ubuntu — install missing deps
    sudo dpkg -i theonermm-agent.deb
    sudo apt-get install -f  # Fix missing dependencies
    # RHEL/CentOS/Rocky
    sudo rpm -i theonermm-agent.rpm
    # If dependency error:
    sudo yum install theonermm-agent.rpm  # yum resolves deps automatically

  2. Unsupported Linux distribution The agent supports Ubuntu 20+, Debian 11+, RHEL/CentOS/Rocky 8+, and Fedora 36+. Older versions or other distributions are not supported.

Script Output Not Appearing​

Symptom: A script runs successfully (status completed, exit code 0) but the output panel shows no content.

Causes and resolutions:

  1. Output size limit exceeded Scripts that generate more than 10 MB of output are truncated. The truncation is noted in the job result header.

    • Reduce script verbosity or write output to a file and retrieve it with a file transfer command.

  2. Script writes to a log file rather than stdout The RMM captures only stdout and stderr. If your script writes to a log file, redirect output:

    # Append file content to stdout
    Get-Content C:\app\logs\app.log

Bulk Deployment Failing on Some Devices​

Symptom: A remote command or patch deployment shows completed for most devices but failed for a subset.

Resolution:

  1. Navigate to the job in Remote Commands → Jobs or Patches → Deployments.
  2. Click View Per-Device Results.
  3. The results table shows status, exit code, and error message per device.
  4. Use the per-device error messages to diagnose: common causes include device offline at dispatch time, permission error on specific devices, or platform-specific command syntax issues.
  5. Filter to failed devices and use Retry on Failed to re-dispatch only to the devices that need it.