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
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? On macOS, read the managed preferences. If EnrollmentToken or OrgSlug is missing, the profile has not applied: check it is scoped and installed. On Windows, run doctor, which prints the organization id, API URLs, and their source:
   • installer-registry: the MSI properties landed
   • Empty values: the MSI was installed without its properties and the client is running local-only. Fix the install command in your MDM and reinstall
   • registry: a leftover HKLM\SOFTWARE\Policies\Merge\WorkforceClient key from an earlier setup is overriding the install properties. Delete it and restart the service
3. Is the token valid? A revoked or expired enrollment token is refused at enrollment. Generate a new one in Devices → Deployment and update your MDM
4. Can the device reach the API? Confirm HTTPS to your regional Merge API host resolves and connects. On Windows, the usual culprit is a proxy that requires authentication, since the service runs as LocalSystem and does not inherit the user’s proxy credentials

Read the client’s error code

When the API rejects a device, it returns a code that tells you whether the employee can fix it.

Only device_revoked is permanent. If you did not revoke the device, check whether someone revoked its enrollment token and re-enrolled it.

A device shows as unattributed

No employee has been resolved for the device, so it has no governed AI path. It shows in Devices with an empty employee column.

1. Has the employee signed in? Identity resolves when they sign in from the menu bar prompt. With MenuBarPresence set to silent, the panel is hidden but the prompt still appears
2. Is the employee synced? A sign-in for someone SCIM never provisioned has no employee record to attach to. Confirm they appear in Merge
3. Did the sign-in expire? The employee has 10 minutes after clicking Sign in to finish in the browser. After that, the browser shows an expired page for 15 minutes, then cannot connect at all. Either way, clicking Sign in again in the tray works

Once you fix the cause, the device updates on its next heartbeat, 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 your MDM’s ExpectedIdentity variable. It is a signal, not an error, and does not show in the fleet view yet. The usual causes:

1. A reassigned laptop with a stale inventory record. The sign-in authenticated the current user, and your MDM still lists 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. This is correct. To silence the alert, remove the assigned user from the MDM record

Nothing an employee does on the laptop can make the wrong identity resolve: identity comes from a verified IdP token, never a local file.

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, so one session’s identity does not carry to 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
3. Is the employee still active in your IdP? Deprovisioning revokes AI access at the next check-in
4. Has the Gateway key been minted? The client mints it only after identity resolves, so a device that resolved moments ago gets its key on the next heartbeat

A device stopped reporting

The client heartbeats every five minutes, and the fleet view marks a device not reporting after 30 minutes of silence. The device is off, offline, or someone with administrator rights stopped or removed the client.

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 blocked locally. With enforcement on, this corrects itself: after 14 days the client fails closed and AI access stops

The configuration profile will not download

Devices → Deployment refuses to generate the profile, and says so, when the desktop client signing team id is not configured for your environment. The profile must name the signing team, or it would approve nothing. There is nothing to fix in your MDM. Contact Merge support.

macOS prompts the employee

Any prompt means a payload is missing or arrived late.

If the package installed before the profile, the prompt already appeared and the profile will not retract it. Deploy the profile, then restart the device.

Enforcement is on in the dashboard but nothing is enforced

Three things hold enforcement off, all intentional.

1. Policy signing is not configured yet. This applies to every organization today. Enforcement needs an Ed25519-signed policy, production signing keys do not exist yet, and the client refuses unsigned policies. Your Enforce choice is saved, and the settings page says it is not applied yet
2. PolicyMode is observe in your macOS profile. The dashboard cannot override it. Change it in your MDM
3. Enforcement mode is observe in the dashboard. It is one organization-wide setting under Devices → Deployment → Configure your desktop client

A config file keeps drifting back

It is not the client yet. In observe mode the client changes nothing, so a file that keeps reverting is another tool, an MDM script, or a dotfile manager.

A Claude Code or Codex CLI config that lost its Gateway settings usually means the employee clicked Disconnect in the tray. Connect Gateway in the same row restores them.

Once enforcement is in force, the client restoring its own marked block is expected. If it reverts a legitimate configuration, change the policy rather than working around it on the device.

Conflicts with EDR or a network client

The client works alongside 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 enforcement to observe, in your macOS profile’s PolicyMode or in the dashboard. Enforcement stops at the next policy fetch, and visibility continues
2. If the problem persists, stop the service. The client does not filter network traffic today, so stopping it returns the machine to its pre-install state
3. Send Merge support the diagnostics along with the name and version of the other product

On macOS, another product holding full disk access does not block the client, but a profile that arrives after the package does. If discovery reports nothing, confirm the profile installed first before looking for a conflict.

Reset a device

Reinstalling the package over the top replaces the app and daemon and restarts the client, but keeps its state, so the device returns with its previous enrollment. On Windows, reinstall with the install properties from Devices → Deployment, which carry your enrollment token, organization id, and API URLs.

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

On Windows, a reinstall or upgrade keeps the old tray app running until the employee’s next logon. If the tray looks stale, have them sign out of Windows and back in.

Next steps