macOS Forwarder Troubleshooting

This guide covers common macOS forwarder issues and how to resolve them. For log collection instructions, see What to Check First.

Forwarder not starting after installation

Symptoms: Installation completes without errors but the forwarder does not appear active in Stairwell, or the asset shows as offline.

Steps:

1. Check whether the forwarder process is running:
   Bash

   ps aux | grep -i inception

2. If the process is not running, check for a launch daemon:
   Bash

   sudo launchctl list | grep stairwell

3. If the daemon is not loaded, it may have failed to load due to missing system extension approval. Open System Settings → Privacy & Security and look for a pending approval request from Stairwell.
4. If a System Extension approval is pending, approve it and restart the forwarder:
   Bash

   sudo launchctl kickstart -k system/com.stairwell.forwarder

Common cause on managed devices: The MDM profile that pre-approves the system extension was not pushed before the forwarder was installed. The extension requires user or MDM approval before it can load. See Install with Jamf or Install with Kandji for the correct profile deployment sequence.

Privacy & Permissions (PPPC) errors preventing file access

Symptoms: Forwarder is running but file collection is incomplete. Logs show permission denied errors on certain directories.

What is happening: macOS requires explicit PPPC (Privacy Preferences Policy Control) approvals for applications to access certain directories — including Desktop, Documents, Downloads, and removable volumes. Without these approvals, the forwarder cannot collect files from those paths.

Steps for managed devices:

1. Confirm that your MDM profile includes Full Disk Access for the Stairwell forwarder. The bundle identifier is com.stairwell.forwarder.
2. Push the updated profile and verify it appears in System Settings → Privacy & Security → Full Disk Access with Stairwell listed and enabled.

Steps for manually-managed devices:

1. Open System Settings → Privacy & Security → Full Disk Access.
2. Click the + button and add the Inception Forwarder application from /Applications.
3. Restart the forwarder service.

Anti-tamper is blocking uninstall or upgrade

Symptoms: Attempting to uninstall or upgrade the forwarder fails with a permission error, even when running as an administrator.

What is happening: The macOS forwarder includes anti-tamper protection that prevents the forwarder binary and its supporting files from being modified or removed by non-Stairwell processes. This is by design to prevent malware from disabling endpoint visibility.

Disabling anti-tamper for maintenance:

Anti-tamper can be temporarily disabled via your MDM or via a signed management command from Stairwell. Contact your Stairwell account team to obtain a temporary disable token for planned maintenance windows.

⚠️

Do not attempt to force-remove forwarder files by booting into recovery mode or using sudo rm -- this can leave the system extension in a broken state that requires OS-level repair.

For full instructions, see macOS Anti-Tamper.

Asset not checking in after upgrade

Symptoms: After upgrading the forwarder via MDM or manually, the asset's last-seen timestamp stops updating in Stairwell.

Steps:

1. Verify the new version is installed:
   Bash

   /Applications/Inception\ Forwarder.app/Contents/MacOS/inception_forwarder --version

2. Check that the forwarder service is running (see Forwarder not starting above).
3. If the service is running but check-ins have stopped, the registration credentials may have been cleared during upgrade. Check the forwarder configuration:
   Bash

   sudo defaults read /Library/Preferences/com.stairwell.forwarder

   Verify that EnvironmentId and RegistrationToken are present and correct.
4. If credentials are missing, re-register the asset by running the installer again with valid credentials.

Debug bundle collection

If you cannot resolve the issue and need to escalate to Stairwell support, collect a debug bundle:

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

The script produces inceptionDiagnose.zip in a Finder window. If you receive "command not found," download the script directly:

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

Provide this bundle along with the macOS version, forwarder version, and a description of the issue to Stairwell support.