Troubleshoot the SuperIT RMM agent

Each section below is a symptom you might see with the SuperIT RMM agent on a Windows device (the macOS and Linux agents are in Beta), its cause, and how to fix it. Most fixes start with the agent's log, C:\ProgramData\SuperIT\superit.log. To see its last entries, run this in PowerShell on the device:

Get-Content -Path C:\ProgramData\SuperIT\superit.log -Tail 50

Each line is a JSON object. The msg field says what happened, and the error or reason field says why.

The device doesn't appear in Devices

Cause: The SuperIT RMM agent hasn't registered with SuperIT. A device normally appears in Devices within a few minutes of installing. If it doesn't, the SuperIT service isn't running, the agent has no install key, its key was rejected, or it can't reach SuperIT.

Fix:

1. Check the service is running:

   Get-Service -Name SuperIT

   If it isn't listed, the install didn't finish. Run the installer again with a log (/l*v "%TEMP%\superit-install.log") and check the end of the log. If it is Stopped, start it with Start-Service -Name SuperIT.

2. Check you're looking at the right team in SuperIT. The device joins the team the install key was generated in.

3. Read the end of superit.log and find the matching message below:

   Log message	Go to
   no install key configured; agent is unregistered	No install key configured
   registration init refused by server with Invalid installation key	Invalid installation key
   agent upgrade required	Agent upgrade required
   agent run failed, retrying with failed to connect	The agent can't connect to SuperIT
   NATS bootstrap credentials file not found	Bootstrap credentials file not found
   superit-agent running in operational mode	The agent is registered. Wait a few minutes, then refresh Devices.

Still stuck: collect the files in Collect logs for SuperIT support.

No install key configured

The log shows no install key configured; agent is unregistered, then agent parked; manual intervention required with the reason no install key configured.

Cause: The SuperIT RMM agent has no install key, so it can't register. This happens when the MSI was installed without INSTALLKEY, or the key was left blank in the setup wizard. The agent waits until it has a key and is restarted.

Fix:

1. Generate a key in Devices → Add new device in the device's team, if you don't have one.
2. Open C:\ProgramData\SuperIT\config.yaml in a text editor running as an administrator.

3. Add this line at the top level (not indented), or replace the commented # install_key: "" line:

   install_key: "<your-install-key>"

4. Save the file and restart the service:

   Restart-Service -Name SuperIT

Alternatively, set the system environment variable SUPERIT_INSTALL_KEY to the key and restart the service. Keep the key in place afterwards: the agent uses it every time it starts.

Still stuck: check the log again after the restart. The agent logs install key found, starting registration when it reads the key.

Invalid installation key

The log shows registration init refused by server with an error that starts registration rejected (init): error (Invalid installation key: ..., then agent parked; manual intervention required with the reason registration rejected by backend.

Cause: SuperIT rejected the install key. The text after Invalid installation key: says why:

The agent stops trying after a rejection, and only tries again when the service restarts.

Fix:

1. Check the key in C:\ProgramData\SuperIT\config.yaml (install_key) is complete. Keys are about 200 characters long. If you deploy with an RMM tool, check the custom field you store the key in holds the whole key; some single-line text fields cut it short.
2. If the key is revoked, used up or you aren't sure, generate a new key in Devices → Add new device in the device's team.
3. Put the key in config.yaml as described in No install key configured, and restart the service.

Still stuck: send SuperIT support the log lines containing Invalid installation key. Don't send the key itself.

Agent upgrade required

The log shows a registration error containing agent upgrade required.

Cause: The installed SuperIT RMM agent is too old for SuperIT to register. Older versions register in a way SuperIT no longer accepts.

Fix:

1. Download the latest installer from Devices → Add new device.
2. Install it over the existing agent with the same install key. See Install the SuperIT RMM agent.

The agent can't connect to SuperIT

The log shows agent run failed, retrying with failed to connect or failed to connect to NATS. You may also see NATS server unreachable, attempting websocket fallback.

Cause: The device can't reach SuperIT's messaging service at connect.ngs.global. The SuperIT RMM agent first tries port 4222. If that is blocked or times out, it tries a WebSocket connection to the same host on port 443. If both fail, it waits and tries again, waiting longer after each failure, up to an hour between attempts.

Fix:

1. Test the two ports from the device:

   Test-NetConnection connect.ngs.global -Port 4222
   Test-NetConnection connect.ngs.global -Port 443

   At least one must show TcpTestSucceeded : True.

2. If both fail, allow outbound TCP to connect.ngs.global on port 4222, or on port 443, in your firewall. The full list of hosts is in SuperIT RMM agent requirements.

3. If the device can only reach the internet through a proxy, see Proxy servers: the agent's connection to connect.ngs.global doesn't use a proxy.
4. If DNS fails (Test-NetConnection can't resolve the name), fix name resolution on the device. The port 443 fallback uses the same host name, so it won't help.
5. Restart the service to retry straight away: Restart-Service -Name SuperIT.

When the fallback works, the log shows connected to NATS over websocket fallback, and the agent works normally over port 443.

Still stuck: send SuperIT support the output of both Test-NetConnection commands and the log lines that mention NATS.

NATS bootstrap credentials file not found

The log shows NATS bootstrap credentials file not found: C:\ProgramData\SuperIT\ngs-bootstrap.creds.

Cause: The file the SuperIT RMM agent registers with is missing, usually because it was deleted or quarantined by security software.

Fix:

1. Check your antivirus or EDR quarantine for ngs-bootstrap.creds, restore it, and add an exclusion for C:\ProgramData\SuperIT\.
2. Otherwise, reinstall the agent with the latest installer, which puts the file back.

Security software blocks the install, updates or commands

Cause: Application control or EDR software, such as ThreatLocker, blocks superit-agent.exe, the installer, superit-updater.exe, or the powershell.exe processes the agent starts. Signs include:

• The MSI is blocked or the install rolls back.
• The device stops updating: the log shows attempting to download update but the version in Devices → Agent version doesn't change.
• Commands SuperIT runs take a long time and then fail with COMMAND_TIMEOUT: Command execution timed out, with no output. Some application control products delay every powershell.exe launch, which can use up a command's time limit.

Fix:

1. Allow the SuperIT RMM agent by its code signing certificate, issued to Super IT Pty Ltd, rather than by file hashes. File hashes change with every automatic update.
2. Allow superit-agent.exe to start powershell.exe, and superit-updater.exe to start powershell.exe and msiexec.exe.
3. Allow update MSIs signed by Super IT Pty Ltd to run from the SYSTEM account's temp folder.
4. If commands time out, check your PowerShell policy: allow powershell.exe started by superit-agent.exe to run without being held for inspection or approval.

For ThreatLocker, follow Allow the SuperIT RMM agent in ThreatLocker. The same rules apply to other products. For the full list of files, processes and hosts, see Security software. Still stuck: send SuperIT support your security product's block log entries for the time of the failure.

Duplicate or missing devices after imaging or cloning

Cause: The SuperIT RMM agent stores the device ID SuperIT gave it in C:\ProgramData\SuperIT\identity.json. If you image or clone a device after the agent registered, every copy starts with the same ID. SuperIT compares each copy's hardware identifiers (SMBIOS UUID, BIOS and motherboard serial numbers and Windows machine GUID) and splits copies that differ into separate devices. Copies whose hardware identifiers also match, such as virtual machines cloned without sysprep, can't be told apart.

When the agent starts on a copy, its log shows backend issued a different agent id (clone split or reissue).

Fix:

1. For devices you're about to image, reset the agent's identity as the last step before capture. See Device identity and imaging.
2. For a copy that already shares an identity with another device, contact SuperIT support with the names of the affected devices.
3. For virtual machines, give each clone its own SMBIOS UUID and run sysprep /generalize so it gets its own Windows machine GUID.
4. Remove any leftover duplicate from Devices.

Still stuck: send SuperIT support the log lines containing agent identity from each affected device.

Moving a device to a different team

Cause: The SuperIT RMM agent keeps its registration and install key from the first team. Installing it again with a key from another team may not move it.

Fix:

1. Uninstall the agent from the device and remove its leftover data. See Uninstall the SuperIT RMM agent and use -RemoveData, or follow Remove leftover data.
2. In SuperIT, open the old team, go to Devices, and remove the device.
3. Install the agent again with an install key from the new team.

A removed device comes back

Cause: Removing a device in Devices only removes it from the list. The SuperIT RMM agent keeps running on the device, and registers again the next time it restarts.

Fix:

1. Uninstall the agent from the device first. See Uninstall the SuperIT RMM agent.
2. Then remove the device in Devices.

Updates aren't installing

Cause: The SuperIT RMM agent checks for updates every hour. An update can be delayed or blocked because:

• the agent is waiting for running commands to finish (up to 90 minutes),
• the device can't reach updates.superit.ai on port 443,
• security software blocks the download, superit-updater.exe or msiexec.exe, or
• the new version is installed but waiting for a restart to replace a locked file.

Fix:

1. Search the log for update messages:

   Select-String -Path C:\ProgramData\SuperIT\superit.log -Pattern "update" | Select-Object -Last 20

2. Match what you find:

   Log message	What to do
   current version is up to date	Nothing. The device has the latest version for its channel.
   update deferred until pending command outcomes are collected	Wait. The update installs once commands finish, or after 90 minutes.
   update check failed with failed to download manifest	Allow HTTPS to updates.superit.ai. See Network requirements.
   SHA256 verification failed	The download was altered or incomplete, often by a web filter or proxy. Allow updates.superit.ai without inspection.
   update already installed, waiting for a restart to replace the running agent	Restart the device when convenient.
   update failed	Check security software, as in Security software blocks the install, updates or commands.

3. To update straight away, install the latest MSI over the existing agent. You don't need the install key for an upgrade.

Collect logs for SuperIT support

When you contact SuperIT support about the SuperIT RMM agent, send:

1. The device name, as shown in Devices, and the SuperIT team it should be in.
2. The agent version: run Get-Service -Name SuperIT | Select-Object DisplayName.
3. The log files: copy C:\ProgramData\SuperIT\superit.log and any superit-*.log.gz files next to it.
4. For install problems, the installer log, made by running the MSI with /l*v "%TEMP%\superit-install.log".
5. For connection problems, the output of Test-NetConnection connect.ngs.global -Port 4222 and -Port 443.

Related

• Install the SuperIT RMM agent
• SuperIT RMM agent requirements
• Configure and update the SuperIT RMM agent
• Allow the SuperIT RMM agent in ThreatLocker