Troubleshooting

Troubleshooting

Reading the log

log stream --debug --info --predicate 'subsystem contains "com.github.macadmins.SupportCompanion"'

Or search for subsystem: com.github.macadmins.SupportCompanion in Console. The helper logs under the same subsystem, so both sides appear together.

For more detail:

<key>DebugLogging</key>
<true/>
<key>FileDebugLogging</key>
<true/>

FileDebugLogging also writes to file, and follows DebugLogging when it is not set itself. Both are re-read as soon as they change, so no restart is needed.

"Gather Logs" in the app collects the log folders for the current mode into a zip — see Modes for which folders those are.

A setting seems to do nothing

First, SupportCompanionCLI prefs to see what the app actually reads.

If the setting grants privileges, it is probably being ignored on purpose. Look for:

Ignoring 'EnableElevation' from /Library/Preferences: settings that grant privileges are only
read from a configuration profile. Deliver it through your MDM.

or, for actions:

Ignoring IsPrivileged for action 'Reset printers': Actions are not set by a configuration profile

Both mean the value was found somewhere that does not count. Configuration explains which keys these are and why.

Other things in this category:

• EnforceAdminAllowlist, PermanentAdmins, ElevationAllowedAdmins and SkipHelperInstall must be device-scoped. A user-scoped profile is not read for them.
• The helper reads /Library/Managed Preferences directly and ignores any file there that is not owned by root, or that is writable by group or others. It logs which file it skipped and why.
• The app and the helper read preferences by different routes, so they can disagree. When they do, the helper's answer is the one that decides, and it logs where it looked.

Every privileged operation fails

Usually an app and helper version mismatch. The helper refuses clients older than 3.0.0, requires the hardened runtime, and requires the app to be running from /Applications/SupportCompanion.app.

Check both versions match:

/Applications/SupportCompanion.app/Contents/Resources/SupportCompanionCLI version
sudo launchctl list | grep SupportCompanion

Reinstalling the package replaces the helper and fails loudly if it does not end up running. If you deploy the helper declaratively, rebuild the assets from the new app and bump ServerToken — see Deploying the helper.

Elevation

Nobody can elevate. EnableElevation must come from a profile, and the helper re-checks it itself rather than trusting the app. Check the helper's log for what it read.

Administrators are being demoted unexpectedly. EnforceAdminAllowlist is on and PermanentAdmins does not list them. The helper logs each demotion with the account name. Remember accounts granted rights by something else, such as Platform SSO's AdministratorGroups.

The helper refuses to enforce the allowlist.

EnforceAdminAllowlist is set but PermanentAdmins is not configured. Refusing to enforce: set
PermanentAdmins, using an empty array if no account should be permanently an administrator.

A missing list is a half-finished configuration, and acting on it would demote every administrator on the Mac. An explicitly empty array is accepted and means what it says.

User installs

The Finder item is missing. ShowInstallerServiceMenuItem follows EnableUserInstalls unless set explicitly. The state is applied at every launch, so quit and reopen the app after changing it.

Everything is refused. The helper reads AllowedInstallers only from /Library/Managed Preferences, and drops entries that cannot match anything, logging each one:

Ignoring an AllowedInstallers entry: 'Zoom' has a TeamID but no PackageIdentifier or
BundleIdentifier. Add one, or set AllowAnyIdentifier to allow everything that team signs

A missing allowlist logs No administrator-defined AllowedInstallers found and allows nothing.

One installer is refused although its entry looks right. The sheet gives the reason, and the same text goes to the log. The two that surprise people:

it writes to /Library/LaunchDaemons, which this entry does not allow
it writes to /etc/pam.d, which needs AllowedPayloadPrefixes to permit it

The first means AllowedPayloadPrefixes is set and the package writes somewhere it does not list — add the path or remove the restriction. The second means the package writes to one of the paths that always need naming, listed in User installs#Destinations that always need naming.

it also installs us.zoom.pkg.audiodevice, which this entry does not allow

A distribution package must have every component covered, not just one. Add the missing identifier to PackageIdentifier — see User installs#Packages with more than one component.

Fleet

"Fleet's agent (orbit) isn't installed." There is no /opt/orbit/identifier, so there is no device token.

"The device token couldn't be read or isn't valid." The file exists but is empty or malformed. orbit rewrites it on rotation; the app notices without a restart.

A Sign In button on the Apps page. The server has Fleet Desktop SSO enabled. In-app sign-in is not supported yet, so the button opens the Fleet device page in a browser. See Fleet mode.

Installs report failure when the app was simply open. Fleet's skipped_install flag is newer than Fleet 4.91. On an older server the app cannot tell the two apart.

Desktop info won't turn on

ShowDesktopInfo is read once at launch. Restart the app. Position, size and contents all apply immediately, it is only the window's existence that needs the restart.