Troubleshooting agents

This article is a triage list for the most common agent problems. If you don't find your issue here, contact support.

Regional ingest hosts

Diagnostic commands below use ingest-eu.opsmerge.cloud. If your tenant is in another region (US, etc.), substitute the appropriate ingest hostname (ingest-us.opsmerge.cloud, and so on). The Add agent dialog in OpsMerge shows your tenant's correct ingest host.

First principle: trust the database, not the installer

The single biggest source of confusion in agent troubleshooting is that the installer can report "success" while the agent isn't actually working. The installer's job is to put files on disk and start a service. It's not the authoritative source of "is this agent registered and online".

That source is OpsMerge itself: the Agents list in the app. If the endpoint isn't there with a green Online indicator, the install hasn't worked — regardless of what the install script said.

Where to look

Symptom	Look here
Install script errors	The install script's stdout/stderr
Service won't start	OS service manager + the agent log file
Service runs but no telemetry	The agent log file (rmm-agent.log)
Updater issues (Windows)	Windows Event Viewer → source RMMAgent-Updater
Updater issues (macOS / Linux)	The agent log file (rmm-agent.log)
Connectivity	Outbound network test from the endpoint
Registration	Agent log + the Audit log in OpsMerge

Log file locations

Platform	Agent log	Updater log
Windows	C:\ProgramData\rmm\rmm-agent.log	Windows Event Log, source RMMAgent-Updater (no separate file)
macOS	/var/log/rmm-agent.log	None — the agent updates in place, so updater messages go to the agent log
Linux	/var/log/rmm-agent.log	None — the agent updates in place, so updater messages go to the agent log

On Windows, the update helper (rmm-updater.exe) is a short-lived child process and writes to the Windows Event Log rather than a file. Open Event Viewer, then Windows Logs → Application, and filter by source RMMAgent-Updater. On macOS and Linux there is no separate update helper — the agent replaces its own binary in place, so anything update-related is in /var/log/rmm-agent.log.

Linux: don't use journalctl

The agent writes to /var/log/rmm-agent.log directly, not via systemd's journal. journalctl -u rmm-agent is silent by design — tail -f /var/log/rmm-agent.log is the right command.

Install reported "success" but agent isn't in OpsMerge

The single most common failure mode. Causes, in order of frequency:

1. Outbound NATS (port 4222) is blocked

The agent registers over HTTPS (443) but maintains its live connection over NATS (4222). Plenty of corporate firewalls allow 443 outbound but drop everything else.

Test from the endpoint:

# Linux/macOS
nc -zvw5 ingest-eu.opsmerge.cloud 4222

# Windows PowerShell
Test-NetConnection -ComputerName ingest-eu.opsmerge.cloud -Port 4222

Should report "succeeded" / "open". If it doesn't, talk to the network admin.

2. Token expired between generation and use

Tokens default to single-use with a 24-hour expiry. If you generated one yesterday and just ran the installer today, it's gone.

Fix: generate a new token, re-run with RMM_FORCE=1 (Windows) or --force (Linux/macOS).

3. Cloudflare Bot Fight Mode

If your install command points at app.opsmerge.cloud instead of ingest-eu.opsmerge.cloud, Cloudflare returns an HTML challenge page to curl/PowerShell. The bash/PowerShell parser then tries to execute HTML and fails — but the install script can mask this if it's been written defensively.

Fix: use ingest-eu.opsmerge.cloud. The current install commands in OpsMerge's Add agent dialog do this correctly.

4. The TLS handshake to NATS fails

Less common, but possible if the endpoint's system clock is wildly out (more than a few minutes off NTP). TLS certificate validity windows are time-sensitive.

Fix on Linux: chronyd or systemd-timesyncd should be running. Fix on Windows: Date & Time → Synchronise now. Fix on macOS: System Settings → Date & Time → Set automatically.

Service won't start (Windows)

Look at the Windows Event Viewer → Windows Logs → System for Service Control Manager errors mentioning RMMAgent. Common entries:

• "Access denied" — usually means the install ran as a non-admin user despite UAC accepting. Try the install command from an elevated PowerShell.
• "The service did not respond to the start or control request in a timely fashion" — the agent binary is failing on startup. Look at rmm-agent.log for the actual error.

Manual start: sc start RMMAgent from an elevated CMD.

Service won't start (Linux)

systemctl status rmm-agent
journalctl -u rmm-agent -n 50 --no-pager

journalctl here gives you the start/stop events from systemd, even though the agent's own logging goes to /var/log/rmm-agent.log. The combination of both tells the whole story.

A common Linux failure mode is ProtectSystem=full in the unit file colliding with INSTALL_DIR not being in ReadWritePaths. Fix shipped in agent 0.4.20+ — if you're seeing this on an older version, update.

Agent shows up briefly then goes offline

The agent registered, got its credentials, then failed to maintain the NATS connection. Look at rmm-agent.log for one of:

• TLS handshake error — see "TLS handshake fails" above.
• auth violation — per-agent NATS credentials weren't written server-side. The token registered the agent but the credentials-rendering step failed. Re-run with force.
• connection refused — port 4222 is blocked. See above.

Agent installed on the wrong client

A token is scoped to a single client. If the agent appears under the wrong client, you used the wrong token.

Fix: don't try to "move" the agent — uninstall and reinstall with the correct token. Asset history doesn't transfer cleanly between clients (that's by design — assets at "Acme" shouldn't suddenly appear in "Beta Ltd's" historical data).

Updater issues

Update applied but version didn't change

On Windows, open Event Viewer → Windows Logs → Application and filter by source RMMAgent-Updater. On macOS and Linux, read the agent log (/var/log/rmm-agent.log) — there's no separate updater log. Look for one of:

• "checksum mismatch" — something rewrote the binary in transit. Most commonly a TLS-inspecting proxy or aggressive AV. Allow-list ingest-eu.opsmerge.cloud from any in-line rewriting.
• "apply succeeded" but agent reports old version — service restart raced. Manual fix: sc stop RMMAgent && sc start RMMAgent (Windows) or systemctl restart rmm-agent (Linux).

Updater stuck not checking

Check the agent config:

• Windows: C:\ProgramData\rmm\rmm-agent.yml
• Linux/macOS: /etc/rmm/rmm-agent.yml

The update_check_interval field should be a normal duration (e.g. 6h). If it's 0s it means auto-updates were deliberately disabled.

Manual rollback

In almost every case you don't need to roll back by hand. The Windows updater already rolls back automatically: if the new binary fails its self-test, won't start, or the service exits immediately after starting, the helper restores the previous binary and starts that instead, leaving the bad build on disk as rmm-agent.broken.exe for forensics. The endpoint ends up back on the version it was running.

If a bad version has somehow broken the agent so badly it can't take a remote command and the automatic rollback didn't fire:

Windows (elevated PowerShell): during an update the helper keeps the previous binary alongside the live one as rmm-agent.old.exe. It's deleted once an update succeeds, so it's only present mid-update or after a failure. If it exists, you can restore it:

Stop-Service RMMAgent
Copy-Item "C:\Program Files\RMM\rmm-agent.old.exe" "C:\Program Files\RMM\rmm-agent.exe" -Force
Start-Service RMMAgent

If rmm-agent.old.exe isn't there, re-run the install command from OpsMerge's Add agent dialog instead — it lays down a fresh binary.

macOS / Linux: the agent updates in place and does not keep a backup of the previous binary, so there's no local file to restore. Re-run the install script from OpsMerge's Add agent dialog — it re-downloads and reinstalls the current published binary:

# Linux
systemctl stop rmm-agent
# re-run the install command from the Add agent dialog, then:
systemctl start rmm-agent

# macOS
sudo launchctl unload /Library/LaunchDaemons/cloud.opsmerge.agent.plist
# re-run the install command from the Add agent dialog, then:
sudo launchctl load /Library/LaunchDaemons/cloud.opsmerge.agent.plist

Specific gotchas

Proxmox host: install hangs or NIC drops. Intel onboard NICs with default tso/gso/gro settings have a kernel-level hang bug. Disable with ethtool -K eno1 tso off gso off gro off, then retry.

Non-English Windows: ACL setup fails. Pre-0.4.18 installer hardcoded English SID names ("BUILTIN\Users"). Fixed by using WellKnownSidType values. Update the installer.

Microsoft Store PowerShell denies access. The Store-installed pwsh.exe lives under WindowsApps with per-user ACLs. Service accounts get Access Denied. Use the MSI-installed pwsh.exe or fall back to powershell.exe 5.1.

macOS asks for Full Disk Access on first run. Some collectors (mailbox size, FDA-protected directories) need this. System Settings → Privacy & Security → Full Disk Access → Add /usr/local/bin/rmm-agent. Doesn't affect registration or core monitoring.

Getting help

If you've worked through this article and the agent still won't behave, open a support ticket with:

• The endpoint's OS + version.
• The relevant chunk of rmm-agent.log (last 200 lines is usually enough).
• What the install command output was.
• Whether the endpoint appears in OpsMerge at all (under any client).

We'll pick it up from there.