macOS Forwarder Troubleshooting

On macOS, start with the configuration profiles. The forwarder needs three of them, macOS will not let it do its job without them, and a forwarder missing one installs cleanly, registers, appears in the Assets view, and collects nothing. That silence is the single most common macOS ticket, and it is not a network problem, an install problem, or a licensing problem.

Work through What to Check First as well, since connectivity and TLS inspection affect every platform. But on macOS specifically, check the profiles first.

Which profiles does the forwarder need?

Three, delivered by your MDM, alongside the forwarder package.

Download all three from macOS v1.7.4. Use Stairwell's own profiles rather than hand-building equivalents, because they already carry the identifiers macOS matches on, and a profile that is almost right grants nothing.

Two sequencing notes that account for most of the remaining cases. Push the profiles before or alongside the package, not after: a system extension that has already been blocked once needs the approval and a restart of the forwarder, rather than only the approval. And the profiles are versioned separately from the forwarder, so a forwarder upgrade does not normally mean pushing them again.

The install finished and the forwarder is not running

Check whether the process and its launch daemon are there.

ps aux | grep -i inception

sudo launchctl list | grep stairwell

If neither returns anything, the most likely cause is that the system extension was never approved, so the daemon could not load. Open System Settings, then Privacy & Security, and look for a pending approval request from Stairwell. On a managed Mac, an approval request appearing at all is the signal that the system extension policy profile did not arrive first.

Approve it, or push the profile, then restart the machine and confirm the process is running. If it still is not, collect the debug bundle described at the end of this page and send it to support rather than trying further local repairs, because the failure at that point is inside the extension load rather than in configuration.

The forwarder is running but collecting only part of the disk

That is full disk access, and it is granted by the privacy preferences profile.

macOS gates access to several locations behind explicit approval, including the user's Desktop, Documents, and Downloads folders, and removable volumes. Without approval the forwarder can read the rest of the filesystem and not those, which produces a machine with plausible-looking coverage and specific holes in it, usually exactly where a user would download something worth collecting.

On a managed Mac, push Stairwell's privacy preferences profile and then confirm the result: System Settings, then Privacy & Security, then Full Disk Access, with Stairwell listed and enabled. On a Mac you manage by hand, add the Inception Forwarder application from /Applications to that same list and restart the forwarder.

Do not confuse this with an exclusion. If files are missing from a path you deliberately excluded in policy, that is working as configured, and Asset Configuration is where to check.

Uninstall or upgrade fails with a permission error

The macOS forwarder protects itself against removal, and that protection does not make an exception for an administrator.

This is deliberate, because a forwarder a local process can remove is a forwarder an attacker can remove. To take it off or upgrade it as maintenance, get a maintenance token from your Stairwell account team, which is what temporarily lifts the protection for a planned window.

Do not work around it. Booting into recovery and deleting the forwarder's files, or removing them with sudo rm, can leave the system extension in a state that needs operating system level repair, which is a considerably worse afternoon than waiting for a token.

The asset stopped checking in after an upgrade

Confirm three things, in this order, and all three can be read without a shell.

1. The version Stairwell sees. The Forwarder version column in the Assets view is what the machine last reported. If it still shows the old version, the upgrade did not take and the problem is the upgrade, not the check-in.
2. The process is running. Use the two commands above.
3. Connectivity from that machine. Run swell verify connectivity. An upgrade that coincides with a network change is a common coincidence.

If the version is current, the process is running, and connectivity is clean, the forwarder has most likely lost the configuration the settings profile supplies. Re-push the profiles from your MDM, then collect a debug bundle if that does not restore check-ins.

How do I collect a debug bundle?

Run the bundle script as root from Terminal, which is in Applications, then Utilities.

sudo "/Applications/Inception Forwarder.app/Contents/Resources/generateDebugLogs.zsh"

It takes a minute or two and then opens a Finder window holding inceptionDiagnose.zip. Send that to Stairwell support.

Older forwarders do not ship the script. If the command reports that it cannot be found, download it and run it from where you saved it:

https://downloads.stairwell.com/macos/troubleshooting/generateDebugLogs.zsh

Send the macOS version and the forwarder version with the bundle, plus what changed around the time the problem started. A profile change, an MDM change, and an operating system upgrade are the three that matter most on this platform.

What should I read next?

• macOS v1.7.4, for the package and all three profiles.
• What to Check First, for the causes that are not macOS-specific.
• Pre-Deployment Check, for the connectivity and compatibility commands in full.
• Asset Configuration, if files are missing from paths rather than from the whole machine.