Troubleshooting

This appendix lists the failure modes that generate the largest share of support traffic on NetLock RMM, with a short cause-and-fix for each. It is organised by surface rather than by error code — start from the area your symptom lives in.

Every entry below assumes a working baseline: you can sign in to the Console, the server process is running, and the database is reachable. When any of those are in doubt, check the Logging page first (see A.9) — almost every deeper problem surfaces there before it surfaces in the UI.

X.3.1 Agents and devices

The agent never appears in the Console after installation

Symptom. You installed the agent on a device, the installer reported success, but the device is not in the Devices list.

Likely cause. The agent is waiting in the Unauthorized queue. Unapproved devices do not appear in the main inventory by design.

Fix. Open Devices → Unauthorized Devices at /unauthorized_devices. Confirm the hostname, operating system, and the target tenant / location / group. Approve the entry. If the device is not in the Unauthorized queue either, see the next entry.

The agent does not show up even as unauthorized

Symptom. Installation completed but the device never reaches the Console — no entry in Devices, no entry in Unauthorized Devices.

Likely cause. The agent cannot reach the server. The three common reasons are a wrong server URL in the installer configuration, a network or firewall block between the device and the server, and TLS validation failure against the server certificate.

Fix. On the device, confirm the agent service is running (NetLock_RMM_Agent_Comm on Windows; the netlock-rmm-agent-comm systemd unit on Linux). From the device, verify TCP reachability to the server URL and port — but note that a device whose only route to the internet is a forward proxy has no direct TCP route by design, so a failing test there does not mean the device is misconfigured; see the next entry. Check the server's own logs on the /logging page for rejected connection attempts — the source IP on the rejection is the device's apparent source IP, which is useful when a NAT or reverse proxy is in the path. For a detailed on-device view, enable debug logging on the agent and collect its log files — see Debug an agent.

The device is behind an HTTP proxy and never comes online

Symptom. The device has no direct route to the internet and reaches everything through a forward proxy. The installer aborts at the connectivity check, or the installation succeeded but the device stays offline: the Comm agent works in offline mode, the Remote agent never connects to the command hub, and remote control, remote shell and tunnels are unavailable.

Likely cause. The agents determine the server address they talk to from a reachability check. Without a proxy configuration that check has no route to take, so the address stays empty and nothing downstream can connect. Ambient settings do not help by themselves: the three services run as LocalSystem on Windows and therefore see no per-user internet settings, and on Linux a systemd system unit inherits neither /etc/environment nor a login shell.

Fix. Install the agent with the proxy parameters of the Standard Installer, or with a proxy object inside the server_config.json you hand to clean; both are described in Devices behind an HTTP proxy. On Windows the machine-wide WinHTTP proxy written by netsh winhttp set proxy is picked up automatically as a fallback when no direct connection works, and on Linux the same is true for HTTPS_PROXY / HTTP_PROXY / NETLOCK_PROXY placed in /etc/default/netlock-rmm.

An authenticating proxy that answers with 407 is called out separately by the installer. It means the network path is fine and only the credentials were refused — check --proxy-user / --proxy-pass, or use --proxy-auth default on a domain-joined machine.

A device that is already offline because of the proxy cannot update itself into a version that supports this. Such devices need one manual re-install with a current installer.

Once the device is online, patch downloads are a separate matter: Patch Management drives the Windows Update Agent, which takes its proxy from the machine-wide WinHTTP configuration or from a WSUS and not from the NetLock proxy setting. A device that reports patches but never downloads them needs netsh winhttp set proxy or a WSUS as well — see What the proxy setting does not cover.

A device turns up under Unauthorized Devices although nobody deauthorized it

Symptom. A device that was authorized and working appears in Devices → Unauthorized Devices again, sometimes repeatedly, and the audit log holds no matching deauthorize entry.

Likely cause. The server deauthorizes a device on its own in three cases: the hardware ID the agent sends no longer matches the stored one (a mainboard replacement, a VM copied or moved with a new SMBIOS UUID, an image restored on other hardware, a cloned image sharing one access key — and, on Windows agents before version 3.3.0.1, a WMI query that failed at boot or a different first disk, because those agents computed the ID from the disk serial on every start instead of keeping it in hardware_id.json), a reinstall with a new access key matched the device by name and hardware ID, or the license limit was exceeded and the newest devices were deauthorized. A device that was already unauthorized when its agent was updated to 3.3.0.1 is migrated to the new hardware ID format in place and needs one manual re-authorization, after which it stays stable.

Fix. Use the Authentication log row action on the device's row in Unauthorized Devices (permission "Authentication log"). The rows name the reason, the endpoint, the remote address and both hardware IDs, so the case is visible at a glance; the reasons and what to do about each are listed in Debug an agent, and the inputs of the hardware ID and the file it is kept in are described in How the hardware ID is computed and stored. Re-authorize the device afterwards.

The Android app says "Cannot reach the server" although the server is reachable

Symptom. The NetLock RMM Android app shows Cannot reach the server / Server nicht erreichbar right after an enrollment that looked successful. Windows, Linux and macOS agents on the same server work normally. The device never appears in the Console, or appears once and stays unauthorized. With server logging enabled, Debug.txt shows requests to /Agent/Mobile/Verify_Device being answered 401; from server version 3.2.0.4 on, Warning.txt names the endpoint and says the package guid was not sent.

Likely cause. The server sits behind a reverse proxy that removes HTTP header names containing underscores. nginx does this by default (underscores_in_headers off), and some WAFs and load balancers normalise the same way. Android app versions up to 3.1.0.8 send the package guid as Package_Guid, so on such a proxy the header never reaches the server and every mobile request is refused before the device is looked at. The desktop agents send Package-Guid with a hyphen and are unaffected, which is why only the phones fail. Traefik, as configured in the Docker install guide, forwards both spellings unchanged.

Fix. Update the Android app to 3.1.0.9 or later — it sends Package-Guid. The app is distributed through Google Play and receives the update through the store like any other app.

To fix it immediately, or for devices that cannot be updated yet, allow underscored header names on the proxy. With nginx, add underscores_in_headers on; to the server block for the NetLock host and reload:

nginx -t && systemctl reload nginx

The phones reconnect on their next sync, within 15 minutes. On other proxies the equivalent setting is HttpProtocolOptions / RequestHeader handling on Apache (mod_proxy forwards underscored names by default, but mod_security and similar filters may not), preserveHostHeader plus the absence of a header filter on HAProxy (http-request rules), and the WAF's header-normalisation rule set on a cloud load balancer or CDN. Traefik needs no setting.

A NetLock RMM server from version 3.2.0.4 on additionally reads the package guid from the request body when neither header arrives, so upgrading the server repairs affected devices without any proxy change and without an app update.

A device reports Offline despite the agent running

Symptom. The device shows Offline in the Console, but the agent service is running on-device.

Likely cause. The sync interval on the device's policy is longer than you expected, the agent is running but unable to reach the server (intermittent network), or the agent crashed silently and did not restart.

Fix. Check the Agent tab on the device's assigned policy for the configured sync interval — valid values are 5 to 1440 minutes. Increase it only if you accept longer detection windows. Restart the agent service on the device; when the agent comes back up it emits a fresh check-in that moves the Console to Online. If the problem recurs, look at the agent logs on the device and at the server-side /logging page for the device's identifier around the transition window.

A device reports no_assigned_policy_found

Symptom. The device detail view shows no_assigned_policy_found in the policy field.

Likely cause. No automation's condition matches the device and no default policy is set, so no policy has been selected for it. Policies do not attach to devices, locations, or groups directly — they route through Automations, with the default policy as the only fallback.

Fix. Open Automations and review the list for an enabled rule whose conditions all hold for this device (device, tenant, location, group, internal IP, domain, platform or a device attribute); Check matching devices in the rule's dialog shows whether it matches. Create a new automation if none exists. Remember that among the matching rules the one with the lower priority number wins — if the wrong automation is winning, raise its number, narrow it, or give the rule you want a smaller number (a Device rule for the single machine gets 100 by default). Automation changes force an immediate re-evaluation on the affected devices. See Chapter 5 — Automations. Or mark a default policy on the Policies page (Set as default policy in the actions column); it applies to every device that no automation reaches (see Chapter 6.2).

A policy edit has not taken effect on a device

Symptom. You edited a policy, saved, and the device has not picked up the change.

Likely cause. The device has not synced since you saved. Policy changes apply on the agent's next sync cycle.

Fix. If the delay is unacceptable, use the Force Sync action on the device detail page (requires devices_force_sync). Check the Events page for a deployment record — each policy deployment is logged and tells you which revision the device is on. If the device syncs but the change is still not visible on-device, duplicate the policy and re-assign through the automation; a corrupted stored policy is rare but not impossible.

X.3.2 Notifications

Email notifications never arrive

Symptom. Events that should trigger email stay silent; nothing arrives in the recipient's inbox.

Likely cause. The global SMTP configuration has not been saved with a passing test, a maintenance window is suppressing sends, or the recipient's severity threshold is filtering the events out.

Fix. Open Notifications → E mail → SMTP settings and re-run Test. The dialog's Confirm action is gated behind a passing test — a configuration that has never tested successfully silently breaks every email recipient on the deployment. Verify the recipient's Severity dropdown is set appropriately (Any delivers everything; Low delivers Low and above). Confirm no maintenance window is currently suppressing notifications. See A.8.2.

Microsoft Teams or ntfy.sh notifications do not arrive

Symptom. Teams channel is silent, or ntfy.sh topic shows no messages.

Likely cause. The webhook URL or topic URL is wrong, the workflow behind a Teams webhook is turned off or fails on the body it receives, or the recipient's tenant scope does not include the tenant the event belongs to.

Fix. Open the channel tab and run Test on the suspect recipient. For Teams, check that the URL still belongs to a live workflow — a URL on webhook.office.com is a classic Office 365 connector, which Microsoft retired in May 2026; create the workflow as described in H.10 and paste the new URL over the old one. A Teams test that passes while the channel stays empty points at the workflow rather than at the connector: its run history names the failing step, and a post step that cannot read the body it was handed means Payload format does not match how the flow is built. For ntfy.sh, verify the topic URL is still current on the receiving side. Check that the recipient's Tenants / Selected tenants scope includes the relevant tenant — an empty Selected tenants list means "all tenants", but a single selected tenant excludes events from others. See A.8.

X.3.3 SSO

SSO sign-in fails with "User is not authorized"

Symptom. A user completes the identity provider's sign-in flow but the Console rejects them with an authorization error.

Likely cause. The user has not been pre-provisioned in Users, their Auth Mode does not include SSO, or the email the identity provider returns does not match the username on the NetLock account.

Fix. NetLock RMM does not auto-provision accounts on first SSO sign-in. Open Users, create the account, set Auth Mode to SSO or Password & SSO, and make sure the Name field matches the email claim your provider returns exactly. Save. Ask the user to try again. See A.4.2.

Saving the SSO configuration restarts the Console

Symptom. You toggled SSO settings and saved, and the Console immediately restarted, booting every signed-in user.

Likely cause. This is expected. SSO configuration changes restart the Web Console so the new identity configuration loads cleanly.

Fix. No fix needed. Plan SSO changes during a maintenance window if the session churn is a concern, and confirm you can still sign in via the old method from a separate browser before you make the change, so you are not locked out if the configuration is wrong. See A.4.2.

SSO button missing on the login page

Symptom. The SSO tile does not appear on the sign-in page even though you configured a provider.

Likely cause. No provider is currently enabled, or the saved configuration failed to load at startup. The SSO tile is not gated on the licence plan — SSO is available on every deployment.

Fix. Re-open Settings → SSO, confirm exactly one provider tab has its Enable switch on, and save. Only one provider can be active at a time — switching one on turns the others off. If the page shows the red SSO Configuration Error! banner, the stored configuration could not be loaded at startup; correct the provider fields and save again.

X.3.4 Remote control

Relay session stuck in Device offline state

Symptom. A relay session you initiated stays in an offline state indefinitely.

Likely cause. The device is genuinely offline, or the on-device Relay App is not running.

Fix. Confirm the device status on the Devices page first. If the device is online, the Relay App may be off or stuck — trigger a Force Sync on the device to reset its side of the relay connection. Check the Relay Server page for the session's state and for errors. See Chapter 9.2.

Remote Control falls back to JPEG over SignalR

Symptom. The remote control window shows lower-quality frames than usual, and the session indicator mentions SignalR rather than H.264.

Likely cause. The Relay's H.264 slots are all in use, or the Relay is unreachable — either case triggers the legacy fallback path that delivers JPEG frames over the Console's SignalR channel.

Fix. This is expected behaviour, not an error. If the lower quality is painful, wait for another session to end or free a slot by closing idle sessions on the Relay Server page. See A.7.

Remote Control disconnects on a device behind a strict corporate network

Symptom. The H.264 session connects, runs for a minute, and drops. JPEG fallback also drops.

Likely cause. A middlebox — firewall, proxy, or deep-packet-inspection appliance — is terminating long-lived WebSocket connections or the relay stream.

Fix. Verify the device can maintain persistent outbound connections to the server and relay. Review the middlebox's session-timeout policy for WebSocket traffic. If you control the relay, log into the relay host and check its own logs for the dropped session.

The Remote agent logs INADEQUATE_SECURITY in Service.Setup_SignalR

Symptom. Remote control, screen sessions and tunnels are unavailable on a device, but the device shows as online in the Console and syncs normally. The Remote agent's Logs\Error.txt (see Debug an agent) contains entries from Service.Setup_SignalR with Failed to start SignalR and a message containing HTTP/2 error code 'INADEQUATE_SECURITY'.

Likely cause. The device runs Windows 8.1, Windows Server 2012 R2 or older, and the server is reached through a reverse proxy that enforces the HTTP/2 cipher-suite rules — Traefik in the setup from the Docker install guide, Caddy, or Apache with mod_http2. These Windows releases have no cipher suite that such a proxy accepts for HTTP/2, so the proxy refuses the HTTP/2 connection the Remote agent opened for its SignalR connection setup. The Comm agent uses plain HTTP/1.1 requests and is not affected, which is why the device still reports online.

Fix. Update the agent. Agents from version 3.2.0.4 on use HTTP/1.1 for the SignalR connection setup and are not affected; the rest of this entry is only needed for devices that are still on an older agent.

For agents that cannot be updated yet, tell the proxy to offer only HTTP/1.1 on the server host name. With Traefik this is a TLS option, and TLS options cannot be defined through Docker labels — they need Traefik's file provider. Against the documented compose file:

1. Create /home/netlock/traefik/dynamic/tls.yml:

   tls:
     options:
       http11only:
         alpnProtocols:
           - http/1.1

2. In the traefik service, add the file provider to command: and mount the directory under volumes::

   command:
     - '--providers.file.directory=/dynamic'
     - '--providers.file.watch=true'
   volumes:
     - '/home/netlock/traefik/dynamic:/dynamic:ro'

3. On the server container, add the option to the rmmserver router:

   labels:
     - 'traefik.http.routers.rmmserver.tls.options=http11only@file'

4. Run docker compose up -d and check that the Remote agent connects — Error.txt stops growing and the device becomes remote-capable in the Console.

Naming the option default instead of http11only applies it to every TLS router of that Traefik instance without a router label; this is broader than needed, because it also switches the web console to HTTP/1.1. Traefik selects the TLS option by the host name of the request, so with separate host names for server and console the label on rmmserver affects only the agent endpoint.

Note: Only the ALPN / HTTP-version negotiation changes. Certificates, TLS versions and cipher suites stay exactly as they are; nothing about the encryption of the connection changes. The option can be removed once all agents are updated.

Note: Restricting the proxy to AEAD-only cipher suites (cipherSuites: in the TLS option) is not a fix. Windows 8.1 and Server 2012 R2 have none of them, and the device could then not open a TLS connection to the server at all.

X.3.5 Collections

A custom field value does not populate on the device detail page

Symptom. A custom field renders but its value is blank or stale.

Likely cause. The Job that feeds the field failed on the device, or the Job has not run since the field was created.

Fix. Identify the Job feeding the field on Manage Custom Fields. Review its last execution on the device. If the Job is marked Hidden, its outcomes do not surface in the Events page — run it manually from the device detail page's Job list or from the Jobs management page to surface the failure. Fix the Job's Script or parse regex, then let it run again. See Chapter 8.4.

Application Control is not blocking an application I expected it to

Symptom. A user launched an application that is not whitelisted in any attached ruleset, and Application Control did not stop the launch.

Likely cause. The ruleset is not attached to the device's policy, the policy has not synced since the ruleset was attached, or Application Control itself is disabled on the policy.

Fix. Open Policy Settings → Windows → Application Control on the device's policy. Confirm the ruleset is attached and the master switch is on. Force-sync the device. If Application Control is attached and synced, check the Blocked Applications tab on the ruleset for the launch attempt — if the attempt is not recorded there either, the ruleset is probably not in enforce mode.

App Hub browse shows no apps for a catalogue

Symptom. The Winget, Flathub, or Chocolatey browser is empty.

Likely cause. The catalogue has not been refreshed yet on this deployment, or the server cannot reach the upstream service.

Fix. Click Refresh catalogs on the App Hub page. The refresh runs server-side and pulls the catalogue to the local database. Check /logging for network failures against the upstream catalogue. See Chapter 8.5.

X.3.6 Ticket System

Inbound emails are not creating tickets

Symptom. Customers reply to a department mailbox but no new tickets or replies appear.

Likely cause. The department's IMAP credentials are wrong, the mailbox is unreachable, or the Ticket System is disabled globally.

Fix. Open Tickets → Departments and review the department's mailbox configuration. Run the Test action. Check that Settings → Ticket System → General → Ticket System Enabled is on. Confirm the mailbox is reachable from the server. Note that Blocked File Extensions strips attachments during ingestion — it does not prevent the ticket from being created. If attachments are being stripped but the ticket still does not appear, the issue is not the blocklist.

Ticket list refreshes too slowly

Symptom. New replies arrive by email but the list lags behind.

Likely cause. The background refresh is on a 60-second cadence by design; the real-time toasts are a courtesy, not a replacement for the refresh.

Fix. Click Refresh on the page, or reload the page. If toasts are not arriving either, the Console's persistent connection has dropped — reload to re-establish it. See Chapter 10.3.

X.3.7 Dashboards, Reports, and content surfaces

A dashboard panel shows no data

Symptom. The panel renders but the value area is empty or shows zero.

Likely cause. The panel's SQL query returns no rows, the Visual Query Builder references a table that is not in the allowed-tables list, or God Mode is off and the panel relies on raw SQL that is now restricted.

Fix. Open the panel in the Panel Builder and check the underlying query. Open Settings → Dashboards and verify the referenced tables are ticked. If the panel needs unrestricted SQL, enable God Mode on the same page — but understand that God Mode is a deployment-wide switch that lets every eligible user write queries against the whole schema. See A.12.2.

A report generation fails with a SQL error

Symptom. Generating a report returns an error mentioning an unknown table or column.

Likely cause. Someone tightened the allowed-tables list in Settings → Reports after the template was written, or the schema changed between releases.

Fix. Add the missing table back to the allowed list on Settings → Reports, or edit the template to use only tables that are currently allowed. If the schema changed, duplicate the template and rewrite the query against the current columns. See A.12.3.

A Report Builder widget does not show the God Mode SQL field

Symptom. You expected a raw-SQL editor on a widget but only the Visual Query Builder is visible.

Likely cause. God Mode is off for Reports on this deployment. Raw-SQL editing is a platform-wide setting, not a per-user permission.

Fix. Open Settings → Reports and enable God Mode. The change applies to every user who can edit a report template from that moment.

X.3.8 When the answer is "look at the logs"

Two Console surfaces cover almost every deeper diagnostic.

• Logging at /logging — the live viewer for Console and Server logs. Filter by severity, search by module, and watch lines appear as events happen. Self-hosted only. See A.9.
• Audit at /audit — the immutable record of configuration changes, including who changed what, from which IP, and when. When something used to work and now does not, the Audit log usually names the change that broke it. See Chapter 12.

Between them, they answer most of the "what changed and when" questions that otherwise turn into a hunt across multiple chapters.

Related chapters

• Chapter 3 — Devices
• Chapter 5 — Automations
• Chapter 6 — Policies
• Chapter 12 — Events & Audit
• A.4 — Security: IP whitelist & SSO
• A.7 — Remote screen control
• A.8 — Notifications deep dive
• A.9 — Logging & protocols
• A.12 — Content defaults