Windows Forwarder Troubleshooting

Work through What to Check First before this page. Connectivity and TLS inspection cause more Windows tickets than everything below combined, and neither of them leaves a trace on the host. What follows is the Windows-specific set, in the order it tends to be the answer once the network is ruled out.

Two version-dependent details run through the whole page, because the product was renamed partway through its history and older forwarders still use the old names.

Read the forwarder version from the Forwarder version column in the Assets view rather than from the host. It is faster, and it is the version Stairwell believes the machine is running, which is the one that matters when an upgrade is in question.

Is the forwarder service running?

Open Services (services.msc) and confirm both services for your version are started. Both matter: one is the forwarder, one is its agent, and the machine can look installed with only one of them up.

If a service is stopped, start it. If it will not start, or starts and immediately stops, look in two places in this order:

1. Event Viewer, under Windows Logs, then Application, filtered to the forwarder's service source.
2. The forwarder's own log directory from the table above.

A service that refuses to start after an upgrade is usually a stale service registration left by the previous version. Uninstall the forwarder, reboot, and install the current package from Windows v1.7.9. Reboot before reinstalling rather than after: the point is to clear the old registration, and a reinstall on top of it reproduces the problem.

The asset appears in Stairwell but stopped checking in

Confirm the network first, then the credentials, then the service.

1. Run swell verify connectivity on the host. If TLS inspection is in the path, this is where it shows up. See Pre-Deployment Check.
2. Check that the forwarder's registry key holds the environment ID and token it was installed with. A missing or wrong value here means the forwarder cannot authenticate, and it will keep trying quietly.
3. Confirm the services are running, per the section above.

If the credentials are gone or wrong, reinstall with valid ones from your environment's settings. Note that reinstalling on the same machine normally keeps the same asset, because registration is keyed on stable properties of the host rather than on a fresh identifier each time.

Files that changed are missing, but programs that ran are there

That is what a disabled kernel driver looks like, and it is a policy setting rather than a fault.

With the driver disabled, the forwarder still sees process executions and the DLLs those processes load. It stops seeing file modifications, new files, deletions, and renames. A script that is written, run, and deleted within a few minutes is the case that disappears entirely.

Two things to do about it. The Windows kernel driver setting in the policy is what controls it, and a forwarder in more than one group has its driver disabled if any of those policies disables it, so check every group the asset is in. And if the driver is disabled deliberately, enable a daily backscan for those machines, which recovers new and modified files that persist on disk even though the moment of change was not seen. Asset Configuration covers both settings.

Forwarders report their driver state, so you can confirm which mode a machine is actually in from its asset page rather than inferring it.

The backscan is not progressing

Read the Backscan status column in the Assets view first, with its start and end times. Sleeping means the scan ran out of the window its policy allows and will resume, and Disabled means backscans are turned off in policy. Neither is a fault. Failed is.

When the status is genuinely stuck or failed, the usual cause on Windows is other endpoint protection blocking the forwarder's file reads. Add these to your antivirus and endpoint protection exclusion policies:

Include subfolders for the directory exclusion, and exclude these paths from on-access and real-time protection specifically, not only from scheduled scans. Some vendors require a trailing wildcard on a directory path, as in C:\ProgramData\Stairwell\*, so check the format your product expects.

Running swell verify compatibility on the host lists the endpoint protection and proxy clients it recognizes, which is the fastest way to find out what is on a machine you did not build. It makes no network calls and sends nothing to Stairwell.

If the scan is slow rather than stopped, the answer is more likely a resource limit than a block. See Throttles.

The upgrade reported success and the version did not change

Check what Stairwell thinks happened before you check the host. Windows forwarders report three update outcomes that no other platform does, and each one names its own fix: a reboot is pending, the update could not reach Stairwell, or another installer was already running on the machine when the upgrade was attempted.

For an upgrade pushed through a management tool, the trap is on the tool's side. Confirm the previous version is fully stopped before the new package is applied, and confirm the detection rule for the old version has been cleared. A detection conflict lets the deployment system report success while the old forwarder is still installed and running, which is the case that wastes the most time because two systems disagree and both look confident.

When an upgrade fails repeatedly, do a clean install: uninstall through Add or Remove Programs, reboot, then install the current package. Confirm the result from the Forwarder version column rather than from the installer's exit code.

The same machine appears twice, or changed identity

A forwarder identifies itself with a registration key built from stable properties of the host, and Stairwell looks for an existing asset with that key before creating a new one. When the key changes, you get a second asset for one machine.

The key changes for ordinary reasons: a renamed host, a machine with several real and virtual network adapters where a different one wins, or a device replaced with new hardware under the same name.

From forwarder 1.6.6, you can supply your own key with the STAIRWELL_REGISTRATION_KEY environment variable, read during registration. Set it to something you control that identifies the machine stably, such as your asset management system's own identifier, and the duplicate stops recurring. Changing the key produces a new asset identifier and does not change how the machine is named in the app.

Assets for machines that are genuinely gone can be archived, which retires them from your active fleet without discarding the file history they contributed. See Assets.

What should I gather before contacting support?

• The forwarder version and the Windows version and patch level.
• The logs from the directory for that forwarder version.
• An export of the forwarder's registry key.
• The output of swell verify compatibility, which names the other security software on the host.
• When it started, and what changed around then: an upgrade, a policy edit, a proxy rule, or an endpoint protection update.

What should I read next?

• What to Check First, for the four causes that come before anything on this page.
• Proxy Support, for the registry value that points the forwarder at a proxy.
• Change Logging Level, when support asks for more detail than the default logs carry.
• Windows v1.7.9, for the current installers.