Troubleshoot

This article covers known Rapid7 Agent (Insight Agent) troubleshooting scenarios. For troubleshooting instructions specific to Rapid7 Agent (Insight Agent) connection diagnostics, logs or other Insight Products, see the following articles:

If you need to run commands to control the Rapid7 Agent (Insight Agent) service, see Agent controls.

A large number of my agents have gone stale

An agent is considered “stale” when it has not checked in to the Command Platform (Insight Platform) in at least 15 days (assuming your retention settings do not preclude the possibility of this status). This behavior may be caused by a number of reasons, and can be expected. If a large, unexpected outage of agents occurs, you may want to troubleshoot to resolve the issue.

Expected reasons why a large number of agents go stale

These scenarios are typically benign and no action is needed.

If ephemeral assets constitute a large portion of your deployed agents, it is a common behavior for these agents to go stale. An agent’s status will appear as stale on the Agent Management page after 15 days since checking in to the Command Platform (Insight Platform). After 30 days, stale agents will be removed from the Agent Management page.
If you decommissioned a large number of assets recently, the agents installed on those assets will go stale after 15 days since checking in to the Command Platform (Insight Platform). After 30 days, these assets will be removed from your Agent Management page.

Unexpected reasons why a large number of agents go stale

If one of these scenarios has occurred, you should take troubleshooting steps to ensure your agents are running as expected.

If a mass change was made to your environment that prevents agents from communicating with the Command Platform (Insight Platform) successfully, a large portion of your agents may go stale. To ensure your agents can continue to send data to the Command Platform (Insight Platform), review the Rapid7 Agent (Insight Agent) connectivity requirements.
If Rapid7 Agent (Insight Agent) service is prevented from running by third-party software that’s been recently deployed, a large portion of agents may go stale. To ensure other softwares don’t disrupt agent communication, review the Endpoint Protection Software requirements.

Agent service is present, but won’t start

The Rapid7 Agent (Insight Agent) service will not run if required configuration files are missing from the installation directory. These files include:

config.json
ssl/cafile.pem
ssl/client.crt
ssl/client.key

This is often caused by running the installer without fully extracting the installation package. Complete the following steps to resolve this:

Uninstall the agent. See Agent controls for instructions.
Fully extract the contents of the installation zip file and ensure all files are in the same location as the installer.
Run the installer again.

Inconsistent assessment results on virtual assets

The Rapid7 Agent (Insight Agent) uses the system’s hardware UUID as a globally unique identifier. In virtual deployments, the UUID is supplied by the virtualization software. Improperly configured VMs may lead to UUID collisions, which can cause assessment conflicts in your Insight products.

If you mass deploy the Rapid7 Agent (Insight Agent) to several VMs, make sure you follow the special procedures outlined on our Virtualization page.