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 on Windows; the equivalent systemd unit on Linux). From the device, verify TCP reachability to the server URL and port. 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 proxy is in the path.

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, so no policy has been selected for it. Policies do not attach to devices, locations, or groups directly — they route only through Automations.

Fix. Open Automations and review the list for a rule whose condition matches this device's attributes (Device Name, Tenant, Location, Group, Internal IP, External IP, or Domain). Create a new automation if none exists. Remember that automations evaluate in priority order and the first match wins — adjust priority if the wrong automation is matching. Automation changes force an immediate re-evaluation on every connected device. See Chapter 5 — Automations.

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 connector URL or topic URL is wrong, the receiving service has rotated its identifier, 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. Verify the connector URL (Teams) or topic URL (ntfy.sh) 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. The deployment's licence lacks code-signing availability, or no provider is currently enabled. SSO requires a paid licence that surfaces License.CodeSigned.

Fix. Check the Overview and Licensing pages for licence state. If the licence is valid, 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.

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.

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