Forwarder Troubleshooting
Where to start when a forwarder is installed and Stairwell is not showing what you expect, and which normal states look like failures.
A forwarder that is installed but not delivering what you expect has a small number of causes, and they are not equally likely. Start at What to Check First, which walks them in the order they actually turn out to be the answer: the network, then a proxy that inspects TLS, then a throttle in the group's policy, then a backscan that has not finished. Most tickets end at one of those four. If none of them explains it, the per-operating-system pages below carry the specifics.
Read the next section before you open a ticket, because several of the states that look most like a broken forwarder are the product working as configured.
Which of these is normal and which is a fault?
These six states are reported to support as failures more often than anything else, and none of them is one.
| What you see | What it is |
|---|---|
| Heavy disk read activity and a burst of sightings for hours after install, then a drop | The initial backscan finishing. The drop is the forwarder moving to steady state, where it reacts to new and changed files only |
| Backscan status reads Sleeping | The backscan started and did not finish inside the window its policy allows, or the asset is in sleep mode. It resumes at the next window |
| The forwarder using a small, fixed share of CPU while a scan crawls | A CPU limit in the policy doing its job. See Throttles |
| An asset with no sightings that is still checking in | Sleep mode. The forwarder stays installed and does almost nothing else until it is woken |
| Last seen on a file not updating every time it runs | Repeat sightings of the same file at the same path on the same asset are suppressed for a window, six hours by default |
| Each new batch of machines uploading far fewer files than the first | Deduplication across your environment. A file already collected once is recorded as a sighting rather than uploaded again |
Two more that are specific rather than general. On Windows, a policy that disables the kernel driver leaves process executions and DLL loads visible and stops file modifications being seen, so sightings thin out on purpose (see Windows Forwarder Troubleshooting). And the inconclusive results from swell verify compatibility, unable to determine and No known security agents detected, mean the check could not answer, not that the host is unprotected. Pre-Deployment Check covers both.
Which page do I need?
| Symptom | Page |
|---|---|
| Installed, and nothing is arriving at all | What to Check First |
| The network here goes through a proxy | Proxy Support |
| Collection is slower than expected, or a scan never finishes | Throttles |
| Support asked for logs, or you need more detail in them | Change Logging Level |
| A machine's existing files were never collected, or you want to skip that step | Force or Skip a Backscan |
| A Windows service, registry value, driver, or upgrade | Windows Forwarder Troubleshooting |
| A macOS profile, permission, or system extension | macOS Forwarder Troubleshooting |
A Linux unit, auditd, SELinux, or AppArmor | Linux Forwarder Troubleshooting |
What should I gather before contacting support?
Four things, on every platform, and gathering them first usually shortens the exchange to one round trip.
- The forwarder version and the operating system version. Both are columns in the Assets view, so you can read them without touching the host.
- The asset's identifier, its last check-in time, and its backscan status, from the same view. See Assets.
- Logs from the host, at the default logging level unless support has asked for more. Each per-operating-system page gives the location.
- What changed. Almost every forwarder that stops delivering stopped because something else moved: a forwarder upgrade, a policy edit, a new proxy rule, an endpoint protection update, or a change to egress filtering.
What should I read next?
- What to Check First, the ordered list to work through before anything else.
- Pre-Deployment Check, the two commands that answer "is it the network" in about a minute.
- Asset Configuration, for the group policy that decides what a forwarder collects and how hard it is allowed to work.
- Forwarder Downloads, if the answer turns out to be an upgrade.
Updated 24 days ago