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’s ExpectedIdentity variable carries. It is a signal, not an error, and it does not surface in the fleet view yet. When you notice one, 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. Did the Gateway key ever get minted? The client refuses to mint one until the device resolves to an employee, so a device whose identity resolved moments ago may not have a key yet. It arrives on the next heartbeat

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 things can hold enforcement off, all of them intentional.

1. Policy signing is not configured yet. This is the answer today for every organization. Enforcement travels in an Ed25519-signed policy document, production signing keys do not exist, and the client refuses an unsigned one, so Merge serves no policy at all. Your choice of Enforce is recorded and the settings page says it is not yet applied
2. PolicyMode is observe in your MDM. This is a hard ceiling that the dashboard cannot override. Change it in your MDM configuration
3. Enforcement mode is observe in the dashboard. It is one organization-wide setting on Devices → Desktop client preview, not per Group

A config file keeps drifting back

Not the client, yet. In observe mode it changes nothing on the device, so a config file that keeps reverting is another tool on the machine, an MDM script, or a dotfile manager. Rule those out before you look at the client.

Once enforcement is in force, restoring its own marked block is expected behavior in Enforce mode, and a legitimate configuration being reverted is a policy question rather than something to work around 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 at the next policy fetch; visibility continues
2. If the machine is still wrong, stop the service. The client does not filter network traffic today, so stopping it returns the machine to exactly its pre-install state
3. Send Merge support the diagnostics along with the name and version of the other product

The one interaction worth knowing about is macOS permissions: another product holding full disk access does not prevent the client from having it, but a profile that arrives after the package does. If discovery reports nothing on a device running other endpoint software, check the profile installed before you look for a conflict.

Reset a device

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

Re-enrollment is keyed on the hardware identifier, so the device keeps its existing record and history. It does not keep its attribution: a re-enrollment cannot tell a reinstall from a reassignment, so the employee is cleared and the device shows as Unattributed until someone signs in again. For a genuine reinstall that is one click by the same person.

Next steps