> This page is for Workforce.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Troubleshooting

> How to diagnose the Merge Workforce desktop client when devices do not appear, identity does not resolve, users get prompted, or it conflicts with EDR and network clients.

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

## Collect diagnostics first

Every report should start here.

#### macOS

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

Or gather the pieces by hand:

```bash
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
```

#### Windows

```powershell
& 'C:\Program Files\Merge\merge-workforce-client.exe' diagnose > "$env:USERPROFILE\Desktop\merge-client-diag.txt"
```

Or gather the pieces by hand, from an elevated PowerShell session:

```powershell
Get-Service MergeWorkforceClient
& 'C:\Program Files\Merge\merge-workforce-client.exe' doctor
Get-WinEvent -LogName MergeWorkforce -MaxEvents 100
```

## 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.

| Code              | Meaning                                                         | What the client does                                         |
| ----------------- | --------------------------------------------------------------- | ------------------------------------------------------------ |
| `device_revoked`  | The device credential was revoked in **Devices**                | Stops, and stays stopped. Re-enrollment is the only way back |
| `sign_in_expired` | The employee's session is no longer valid                       | Prompts for a fresh sign-in                                  |
| `org_mismatch`    | The sign-in resolved to an employee in a different organization | Prompts for a fresh sign-in                                  |

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.

| Prompt                                                     | Missing payload                                          |
| ---------------------------------------------------------- | -------------------------------------------------------- |
| "Background item added"                                    | Service management managed login item                    |
| Discovery reports no MCP servers even though configs exist | Privacy preferences policy control with full disk access |

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

#### [Plan your deployment](/merge-workforce/devices/deployment-overview)

Configuration keys and staged rollout

#### [Privacy and data collection](/merge-workforce/devices/privacy-and-data-collection)

What the client collects and what it cannot