What to Check First

Work these four in order. They are not equally likely: connectivity and a TLS-inspecting proxy between them account for most cases of a forwarder that installed cleanly and delivered nothing, a policy throttle accounts for most cases of "it is working but far too slowly", and an unfinished backscan accounts for most cases of "the new files arrive but the old ones never did". Running the two commands on Pre-Deployment Check from the affected machine settles the first two together, and is usually faster than reading a log.

Before you start, confirm you are looking at the right machine in the right place. An asset belongs to exactly one environment, and a forwarder registered into a different environment from the one you are looking at is invisible rather than broken.

1. Can this machine reach Stairwell?

Run swell verify connectivity on the host, or on another machine on the same network path.

The forwarder needs outbound HTTPS on port 443 to *.app.stairwell.com, *.api.stairwell.com, downloads.stairwell.com, and storage.googleapis.com. The failure that hides is a firewall that allows the web app and not the intake hostnames: the forwarder registers, the asset appears, the console looks healthy, and no file data ever leaves the building. That is why the check reports the intake endpoints as their own rows, and why those are the rows that decide whether a deployment collects anything.

A timeout or a refused connection is a firewall or an egress allowlist, and the fix belongs to whoever owns it. Pre-Deployment Check explains how to read each row, including which failures are advisory.

2. Is a proxy rewriting the TLS?

This is the second thing to check and the most expensive one to miss, because nothing about it looks like a network problem.

If your outbound HTTPS goes through a device that terminates TLS, inspects the plaintext, and re-signs it with your organization's own certificate authority, then browsers on those machines accept it and the forwarder does not. The forwarder verifies that it is talking to Stairwell rather than to an intermediary, so it declines and stays quiet. Nothing errors loudly on the host.

swell verify connectivity reports this as possible MITM proxy in its detail column. The fix is to add Stairwell's hostnames to the decryption bypass list, not to change anything on the endpoint. A related case: a device that handles ordinary HTTPS correctly and interferes with HTTP/2 shows up as a gRPC row failing while the HTTPS rows pass.

If the machine reaches the internet only through an explicit proxy, that is a separate question from inspection, and Proxy Support covers how to point the forwarder at one.

3. Is a throttle holding the forwarder back?

Check this when data is arriving but too slowly, or when a scan never seems to finish.

Collection limits live in the policy attached to the group the asset is in, not on the host. A CPU limit, a network limit, a low process priority, or backscan-only mode with a short nightly window will each make a forwarder look stalled while it is doing exactly what it was told. An asset in more than one group takes the most restrictive value of each setting, which is the usual reason a machine is slower than its policy appears to allow.

Throttles lists every limit, its default, and what it looks like from the outside. Two symptoms worth naming here: a backscan whose status reads Sleeping ran out of window rather than failing, and a machine whose sighting timestamps update less often than the file runs is inside the repeat-sighting suppression window, six hours by default.

4. Is the backscan still running, or was it skipped?

Check this when recent files arrive and older ones never did.

When a forwarder is installed it works through the files already on disk, which is separate from reacting to new ones. Until that pass completes, the machine's history in Stairwell is partial by design, and on a dense file server it can stay partial for a good while. The Backscan status column in the Assets view is the authoritative answer, along with its start and end times.

Read the status this way:

If it was skipped at install and you need the machine's existing files, or you want to skip it deliberately on the next rollout, see Force or Skip a Backscan.

What if all four are clean?

Then the question becomes whether the forwarder is running, whether it registered, and whether something on the host is preventing it from reading files. That is per-operating-system work: Windows, macOS, Linux.

Two more causes worth ruling out at this point, because both are silent and both are configuration rather than failure:

• Exclusions and intake filters. A path or filename exclusion stops files being collected at the source, and an intake filter drops them on arrival. Either will produce a forwarder that is demonstrably healthy and a file that is demonstrably absent. Both are set per environment or group, and Asset Configuration covers where.
• Sleep mode. An asset that was put to sleep, individually or as part of a group, records nothing until it is woken. A change of mode can take up to fifteen minutes to reach the host.

Where are the forwarder logs?

By operating system. Collect these at the default logging level unless Stairwell support has asked you to raise it; Change Logging Level covers how, and why to put it back afterwards.

The other files worth knowing on Linux, because they answer three questions without a log at all:

Redact the token before sharing the configuration file with anyone, including Stairwell.

What should I read next?

• Pre-Deployment Check, for the two verify commands in full, and how to read every row of their output.
• Throttles, for the limits that make a healthy forwarder look stalled.
• Forwarder Troubleshooting, for the states that look like faults and are not.