Documentation forSolarWinds Observability SaaS

Troubleshoot SolarWinds Observability Agent issues

When you experience issues with a SolarWinds Observability Agent (Agent), consider reinstalling it.

Installation issues

If your operating system or distribution is supported and the following solutions do not address your problem, Reinstall the Agent.

Error: Agent failed to register to the cluster. Access Token is invalid.

Full error message:

The SWO Agent has failed to register to the cluster at xx-yy.cloud.solarwinds.com. Access Token is invalid.

If you encounter this error when installing the Agent using the bash installation script, check the API token in the script. Make sure the API token is the same as the -AccessToken used in Add Host wizard. If it is different, copy the token from the wizard and use it in the script. See Add a self-managed host.

Error: Agent failed to register to the cluster. Connection problem. Verify SWO_URL.

Full error message:

The SWO Agent has failed to register to the cluster at na-01.cloud.solarwinds.com. Connection problem. Please verify SWO_URL.

If you encounter this error when installing the Agent using the bash installation script, verify the following:

  • Make sure the SWO_URL used in the script is the same as the SWO_URL used in the Add Host wizard.

  • Check the operation status of SolarWinds Observability and its services at https://status.cloud.solarwinds.com/

  • Make sure you are connected to the internet and that the traffic and ports are not blocked. SolarWinds Observability Agent use port 443 for communication.

Error: SWO Agent already installed

Full Linux messages:

  • Warning: The SWO Agent is already installed on this machine. The installation might not succeed. It is recommended to uninstall the SWO Agent before performing a new installation.

  • Error: SWO Agent is already installed and deactivated. Please uninstall the SWO Agent before performing a new installation.

Full Windows message:

  • Warning: Client is deactivated. Please uninstall client and run script again.

If you encounter this issue when installing the Agent using the bash or PowerShell installation script, the SWO Agent was already installed on this host and removed from the Agents page in SolarWinds Observability. The Agent is thus deactivated and cannot be installed.

To address the issue, uninstall the Agent and then re-install it. See Reinstall the Agent.

Warning: Agent already installed. The installation might not succeed.

Full warning message:

SWO Agent is already installed on this machine. The installation might not succeed. It is recommended to uninstall the SWO Agent before performing a new installation.

If you encounter this warning when installing the Agent using the bash or PowerShell installation script, the Agent is installed on this host.

To address the issue, uninstall the Agent and then re-install it. See Reinstall the Agent.

Error: rpmdb open failed

If you encounter the rpmdb open failed error when installing the Agent on a private EC2 instance, rebuild the RPM database.

Error message:

Error: rpmdb open failed

To address the issue, run the following script to rebuild the RPM database:

mkdir /var/lib/rpm/backup
cp -a /var/lib/rpm/__db* /var/lib/rpm/backup/
rm -f /var/lib/rpm/__db.[0-9][0-9]*
rpm --quiet -qa
rpm --rebuilddb
yum clean all

Issues with the Agent service startup after the target host restart

When you have deployed the SolarWinds Observability Agent on a Windows computer and you stop receiving data after the computer restarts, complete the following steps.

  1. In SolarWinds Observability SaaS, click Settings > Agents.

  2. Locate the computer hosting the Agent and review the Agent status. If it is disconnected, the service was not restarted correctly.

  3. On the computer hosting the Agent, open Services.

  4. In Services, locate the SolarWinds UAMS Client service and check its status.

  5. If the service is not running, restart it.

  6. If restarting the service doesn't resolve the issue, right-click the service and set the Startup type to Automatic (Delayed Start).

The automatic startup type will resolve the issue, the Agent in SolarWinds Observability SaaS will be connected, and you should be receiving data.

The Agent fails to install because enabled cipher suites do not match supported ciphers

Enable the supported cipher suites on your servers. See Cipher suites supported by SolarWinds Observability Agent.

Troubleshoot SolarWinds Observability Agent issues

Connection issues

If the Agent status says Disconnected, it might be caused by a connection issue.

  1. Check the Agent logs. Search for issues related to accessing endpoints or blocked ports. See Collect Agent logs from target hosts.

    On target hosts, log files are stored in the following default locations:

    • Windows: C:\ProgramData\SolarWinds\UAMSClient\log\uamsclient.log
    • Linux: /var/log/solarwinds/uamsclient/uamsclient.log

  2. Make sure that the firewall on the host allows access to SolarWinds Observability SaaS all SolarWinds Observability Agent endpoints. See Data centers and endpoint URIs.

Clone a VM with an installed Agent

To observe a cloned VM as a new host in SolarWinds Observability SaaS, run the following code. See Use uamsclient-ctl tool to override the client ID.

uamsclient-ctl bind-new-identity

As an alternative, you can set the UAMS_CLIENT_ID_OVERRIDE and restart the Agent.

Collect Agent logs from target hosts

  1. In SolarWinds Observability SaaS, click Settings > Agents.

  2. Click the vertical ellipsis at the end of a SolarWinds Observability Agent row and select Collect Logs. Agent logs available on the target host start to be downloaded to SolarWinds Observability SaaS.

  3. When the download is complete, you will see a download logs button next to the agent. Click the button to download the logs to your computer.

Agent logs are downloaded as a ZIP archive and are available for download in SolarWinds Observability SaaS for 24 hours. To get a fresh set of logs, repeat the steps above.

Multiple items for one Agent on Agents page

When you see multiple items for one SolarWinds Observability Agent on the Agents page, configure your deployment to override the Client ID.

By default, Agent ID is tied to the external MAC address of the target host. Once the host reboots, a new Client ID is created and a new Agent item based on the ID is displayed in Agents.

To resolve the issue, override the client ID using the uamsclient-ctl tool or an environment variable.

Use uamsclient-ctl tool to override the client ID

To use a randomly generated client ID, run the following code:

Windows PowerShell for a random client ID

C:\'Program Files'\SolarWinds\UAMSClient\uamsclient-ctl.exe bind-new-identity -work-dir $env:programData\SolarWinds\UAMSClient -log-dir $env:programData\SolarWinds\UAMSClient\log

Linux for a random client ID

sudo -u swagent /opt/solarwinds/uamsclient/sbin/uamsclient-ctl bind-new-identity -work-dir /opt/solarwinds/uamsclient/etc -log-dir /var/log/solarwinds/uamsclient

To use a specific client ID, replace <your UUID> with the ID and run the code:

Windows PowerShell for a specific client ID

C:\'Program Files'\SolarWinds\UAMSClient\uamsclient-ctl.exe bind-identity -id <your UUID> -work-dir $env:programData\SolarWinds\UAMSClient -log-dir $env:programData\SolarWinds\UAMSClient\log

Linux for a specific client ID

sudo -u swagent /opt/solarwinds/uamsclient/sbin/uamsclient-ctl bind-identity -id <your UUID> -work-dir /opt/solarwinds/uamsclient/etc -log-dir /var/log/solarwinds/uamsclient

When you set the new identity, the Agent will not be replicated on the Agents page for each reboot. However, if you set the client ID value in the environment variable, the variable value will overwrite the value set by the uamsclient-ctl tool.

Set the UAMS_CLIENT_ID_OVERRIDE [string] variable

Set the client ID value in the UAMS_CLIENT_ID_OVERRIDE [string] variable. If the variable is defined during the client start, the value will be used. This value has priority over the client-id-override value in the dynamic configuration file.

When you set the UAMS_CLIENT_ID_OVERRIDE [string] variable, the defined value will always be used and the Agent will not be replicated on the Agents page for each reboot.

Reinstall the Agent

Reinstall the Agent used for adding hosts via a ready-made script

  1. On the server hosting the SolarWinds Observability Agent, uninstall the Agent. See Uninstall the Agent.

    • On Windows computers, run the uamsclient.msi, select Remove, and complete the wizard.

    • On .deb-based Linux, run the following code.

      sudo dpkg --purge uamsclient

    • On .rpm-based Linux, run the following code.

      sudo rpm -e uamsclient

  2. Remove the SolarWinds Observability Agent from SolarWinds Observability SaaS.

    1. In SolarWinds Observability SaaS, click Settings > Agents.

    2. In Agents, locate the entity hosting the Agent.

    3. Click the vertical ellipsis at the end of the row, and then click Delete.

      See Remove the Agent from SolarWinds Observability SaaS.

  3. Install Agent. See Add a self-managed host.

Reinstall the Agent used by the Network Collector via a ready-made PowerShell script

  1. On the server hosting the SolarWinds Observability Agent, uninstall the Agent. See Uninstall the Agent.

  2. Remove the SolarWinds Observability Agent from SolarWinds Observability SaaS.

    1. In SolarWinds Observability SaaS, click Settings > Agents.

    2. In Agents, locate the entity hosting the Agent.

    3. Click the vertical ellipsis at the end of the row, and then click Delete.

      See Remove the Agent from SolarWinds Observability SaaS.

  3. Install the Agent:

    1. In SolarWinds Observability SaaS, click Add Data in the upper-right corner.

    2. Click Network Device.

    3. On Add Network Device, copy the PowerShell script.

    4. Run the script on the server hosting the Agent. Use PowerShell with administrator permissions.

Reinstall the Agent used by a host via the MSI file with parameters

If you prefer using the MSI file, add the additional parameter METADATA="role:host-monitoring".

  1. On the server hosting the SolarWinds Observability Agent, uninstall the Agent. See Uninstall the Agent.

  2. Remove the SolarWinds Observability Agent from SolarWinds Observability SaaS.

    1. In SolarWinds Observability SaaS, click Settings > Agents.

    2. In Agents, locate the entity hosting the Agent.

    3. Click the vertical ellipsis at the end of the row, and then click Delete.

      See Remove the Agent from SolarWinds Observability SaaS.

  3. Copy or create an API token (Ingestion type), found in the settings area of SolarWinds Observability SaaS. You will need it later. See API Tokens for details.

  4. Start PowerShell with administrator privileges.

  5. In the PowerShell console, go to the folder with uamsclient.msi.

  6. In the following command, replace ....... with the token copied previously, and then run the command.

    msiexec /i uamsclient.msi ACCESSTOKEN="........." METADATA="role:host-monitoring"

Reinstall the Agent used by Network Collector via the MSI file with parameters

If you prefer using the MSI file, add the additional parameter METADATA="role:SiteCollector".

  1. On the server hosting the SolarWinds Observability Agent, uninstall the Agent. See Uninstall the Agent.

  2. Remove the SolarWinds Observability Agent from SolarWinds Observability SaaS.

    1. In SolarWinds Observability SaaS, click Settings > Agents.

    2. In Agents, locate the entity hosting the Agent.

    3. Click the vertical ellipsis at the end of the row, and then click Delete.

      See Remove the Agent from SolarWinds Observability SaaS.

  3. Copy or create an API token (Ingestion type), found in the settings area of SolarWinds Observability SaaS. You will need it later. See API Tokens for details.

  4. Start PowerShell with administrator privileges.

  5. In the PowerShell console, go to the folder with uamsclient.msi.

  6. In the following command, replace ....... with the token copied previously, and then run the command.

    msiexec /i uamsclient.msi ACCESSTOKEN="........." METADATA="role:SiteCollector"