Troubleshooting

An agent does not connect

1. Device list: is the device there and offline, or missing altogether (enrollment failed)?
2. On the PC: read %ProgramData%\RMM\logs\agent.log (warnings and errors also go to the Application event log, source RMMAgent), and check the service with sc query RMMAgent or rmm-agent.exe status.
   • enrollment token is invalid / expired / exhausted: create a new token under Agent enrollment and reinstall with ENROLLMENT_TOKEN=….
   • TLS errors (x509: certificate signed by unknown authority): a proxy intercepts TLS, or a lab CA is not trusted (TLS).
   • the server revoked this installation; stopping, or 401 after running fine: the device was decommissioned or the tenant suspended (close code 4003). Reinstalling with a token re-enrolls the machine.
3. Network: outbound 443 to the portal name and the files name (downloads). WebSockets must pass through web proxies. If WebSockets are blocked, the agent falls back to HTTPS polling every 5 minutes after 10 failed attempts.
4. Server: look for agent connection ended in docker compose logs backend (with RMM_LOG_LEVEL=debug), and at rmm_ws_connections and rmm_ws_disconnects_total.
5. Rate limits: mass installs behind one address are limited by RMM_ENROLL_RATE_PER_MINUTE (HTTP 429). Raise it for the roll-out.

Pushing the agent from AD fails

Push runs on the site connector. The error code shows on the AD computer row.

Code	Cause and fix
dns_failed	The connector cannot resolve the computer name: check DNS on the connector server and stale AD records.
unreachable	No route or a firewall: allow TCP 445 (SMB, used first) or 5985/5986 (WinRM) from the connector server.
winrm_disabled	Only port 445 answers and this connector build cannot use SMB (non-Windows). Run the connector on Windows, or enable WinRM by GPO (Allow remote server management through WinRM + firewall rule).
auth_failed	Wrong push account or password, a locked account, or NTLM blocked by policy.
access_denied	The account is not a local administrator on the target. Add it by GPO (Restricted Groups). UAC remote restrictions (LocalAccountTokenFilterPolicy) apply to local accounts.
copy_failed	The MSI could not be copied: the ADMIN$ share is disabled (AutoShareWks=0) or the service manager is not reachable over SMB, and WinRM is off too; or the disk is full; or the checksum did not match after a WinRM copy. The message says which.
msiexec_failed	The installer failed; the exit code, its meaning and the last installer log lines (tokens redacted) are in the result. Common causes: another installation in progress (1618), a 32-bit Windows (1633), policy (1625), antivirus. The full log is C:\\Windows\\Temp\\rmm-agent-install.log while the push runs.
download_failed	The connector could not download the agent MSI from the files host (after 4 attempts), or its checksum did not match. cannot resolve means the connector server's DNS does not know the files host: on a domain controller whose DNS hosts a zone for the portal's domain, add the record to that zone (check with Resolve-DnsName <files host>). Otherwise check outbound HTTPS and that a stable agent release is published.
timeout	The target took longer than 10 minutes, or is asleep. Retry later, or wake it first.
already_installed	The RMMAgent service already exists; counts as success.
push_credential_required	The AD configuration has no push account (shown when you start the push).

AD sync or the LDAP test fails

Code	Cause and fix
ldap_connect	Host or port unreachable from the connector (389 LDAP/StartTLS, 636 LDAPS), or a wrong host name.
tls	Certificate problem: the DC certificate does not match the name you entered (use the FQDN, not an IP); the issuing CA is not trusted on the connector server (paste it into the CA field); or the DC has no LDAPS certificate (use StartTLS, or install one). Skip certificate verification is for tests only.
ldap_bind	Wrong bind account or password, an expired password, or the DC requires signing/channel binding: use LDAPS or StartTLS, which satisfy it.
ldap_search	The base DN does not exist, or the filter is invalid or too broad for the account's rights.
connector_timeout	The connector did not answer in time: it is offline or busy.

A sync that never starts usually means the connector is offline. Check its status under Active Directory; on the server, sc query RMMConnector and %ProgramData%\RMM Connector\logs\connector.log.

A deployment is stuck

• Targets wait while their devices are offline; the deployment shows how many are pending.
• A maintenance window or the concurrency limit holds targets back.
• A paused deployment starts no new targets.
• A target whose job ended without a result (swept, cancelled, device decommissioned) is settled by the next scheduler pass (every 30 s).

"database is at version …"

The backend and the schema do not match. Run migrate up (upgrade), or start the matching server version (Upgrades).

Slow pages

• Look at rmm_http_request_duration_seconds by route, and at pg_stat_statements.
• Queries over 1 s are logged with their plan (auto_explain).
• See Performance for the seed and benchmark tools.

E-mails do not arrive

• Check the RMM_SMTP_* settings and the backend log for email.send errors; queued e-mails are retried.
• In development, e-mails go to mailpit at http://localhost:8025.
• Links in alert e-mails point at RMM_PORTAL_URL. Invitations and password resets are sent by Entrosity Hub: check the platform service log; their links point at PLATFORM_PUBLIC_URL.