Troubleshooting

Work top to bottom. Most issues are one of the first three.

Collect diagnostics first

Every report should start here.

$
sudo /usr/local/bin/merge-workforce-client diagnose > ~/Desktop/merge-client-diag.txt

$
defaults read /Library/Managed\ Preferences/com.merge.workforceclient.plist
$
sudo launchctl list | grep com.merge.workforceclient
$
systemextensionsctl list | grep -i merge
$
log show --predicate 'subsystem == "com.merge.workforceclient"' --last 1h

The device never appears in the fleet view

Check in this order.

1. Is the service running? If not, the package did not install or it crashed on start. The diagnostics output names the reason
2. Did the configuration arrive? Read the managed preferences on macOS or the policy registry key on Windows. If EnrollmentToken or OrgSlug is missing, the profile or GPO has not applied. On macOS check the profile is scoped and installed; on Windows run gpupdate /force then gpresult /h report.html
3. Is the token valid? A revoked or expired enrollment token produces a 401 in the client log. Generate a new one in Devices → Deployment and update your MDM
4. Can the device reach the API? From the device, confirm HTTPS to your regional Agent Handler API host resolves and connects. A proxy that requires authentication for machine-context traffic is the usual culprit on Windows, since the service runs as LocalSystem and does not inherit the user’s proxy credentials

A device shows as unattributed

Unattributed means no employee has been resolved for that device, so it has no governed AI path. It shows in Devices with an empty employee column. Work down the list.

1. Has the employee completed the one-time sign-in? Identity resolves when they sign in from the menu bar prompt. If MenuBarPresence is silent the panel is hidden but the one-time prompt still appears
2. Is the employee synced at all? A sign-in that resolves to someone SCIM has never provisioned has no employee record to attach to. Confirm they appear in Agent Handler
3. Did the sign-in expire before completion? An abandoned sign-in is refused; the prompt reappears and a fresh attempt succeeds

Attribution reaches the device through the heartbeat, so fixing the cause fixes the device within five minutes. No reinstall needed.

The wrong employee resolved, or there is a mismatch alert

A mismatch means the identity Merge resolved differs from the one your MDM has on file. It is a signal, not an error, and it usually has one of three causes.

1. A reassigned laptop with a stale inventory record. The sign-in authenticated the person actually using it, and your MDM’s ExpectedIdentity variable still carries the previous owner. Fix the MDM record
2. ExpectedIdentity set to a literal rather than your MDM’s variable, so every device expects the same person. Fix the payload or remove the key
3. A shared machine. Identity is per operating system user, so different people resolve in different sessions. That is correct behavior, and you can silence the alert by removing the assigned user from the MDM record

Note that nothing an employee does on the endpoint can cause the wrong identity to resolve: identity comes from a verified IdP token, never from a file on the machine.

AI is blocked for an employee who has a resolved identity

Check in this order.

1. Which operating system user? Identity is per OS user. A resolved identity in one session does not grant another on a shared machine
2. Has the session expired? A device offline for more than 14 days fails closed and must re-resolve. The menu bar says so explicitly
3. Is the employee still active in your IdP? Deprovisioning revokes endpoint AI access by design, at the next check-in
4. Is enforcement blocking a path that was never provisioned? Check the device’s resolved policy in the fleet view. A device in block mode with provisioning disabled has no governed path to fall back to, which is a policy mistake rather than a client fault

A device stopped reporting

The client heartbeats every five minutes. A device that goes quiet is either off, offline, or has had the client stopped or removed, which requires administrator rights on the machine.

1. The fleet view shows how long it has been quiet and the last known state
2. Your MDM reinstalls required software at the next check-in, so a removed client returns on its own
3. If the device is reachable but not reporting, check whether the Merge API host is being blocked locally. With enforcement enabled this is self-correcting: after the 14-day grace window the client fails closed and AI access stops

macOS prompts the employee

Any prompt means a payload is missing or arrived late.

If the package installed before the profile, the prompt has already been presented and shipping the profile afterwards does not retract it. Deploy the profile, then restart the device.

Enforcement is on in the dashboard but nothing is enforced

Three ceilings can hold enforcement off, all of them intentional.

1. PolicyMode is observe in your MDM. This is a hard ceiling that the dashboard cannot override. Change it in your MDM configuration
2. The device is inside its 24-hour soak. Newly enrolled devices stay in observe mode for their first 24 hours regardless of policy. The fleet view shows the remaining soak time
3. The module’s mode is observe in the dashboard. Check the resolved policy for the device in Devices, which shows the effective mode after organization and Group resolution

A config file keeps drifting back

Expected, up to a point. The client restores its own marked block when the file changes. It debounces for two seconds and caps at five reverts per file per hour; past the cap it stops reverting and raises the drift to administrators instead of spinning.

If a legitimate configuration is being reverted, add it to the module’s allowed list in the dashboard rather than working around the client locally.

Conflicts with EDR or a network client

The client coexists with CrowdStrike Falcon, Microsoft Defender for Endpoint, SentinelOne, Sophos, Zscaler Client Connector, Netskope One Client, Cisco Secure Client (formerly Umbrella and AnyConnect), and Cloudflare WARP. If you run something else and the network misbehaves after install:

1. Set PolicyMode to observe in your MDM. Enforcement stops immediately at the next policy fetch; visibility continues
2. If the network is still wrong, stop the service. On Windows every filter the client created is removed automatically by the operating system when the service stops, so the machine returns to unfiltered without a restart. On macOS, disable the content filter module and the extension stops receiving flows
3. Send Merge support the diagnostics along with the name and version of the other product

Where another network client already terminates traffic locally, the client attributes flows to that client’s local endpoint rather than to the original destination. Usage will look under-reported for AI sites the other product handles. That is a limitation of stacking two filters, not a fault, and the fleet view flags devices where it is detected.

Reset a device

$
sudo /usr/local/bin/merge-workforce-client-uninstall
$
sudo installer -pkg MergeWorkforceClient-<version>.pkg -target /

Re-enrollment is idempotent on the hardware identifier, so the device keeps its existing record and history.

Next steps