Common Issues

Diagnose the problems that actually happen — the service not running, a degraded system report, blocked work, stale policy, and what to do about each.

Start here before collecting a diagnostics bundle. The Overview page in the app names what needs attention, and two commands resolve most problems:

agenshield status     # the system report — service, policy, enforcement, agents
agenshield doctor     # check every component and name what is failing

agenshield status ends in one verdict line — ✅ Healthy, ○ Running, not enrolled, ⚠ Degraded, ⛔ Boot-locked, or ✗ Not running — and a degraded report names its reasons right on that line. agenshield doctor --fix attempts a repair for anything it can fix on its own.

Status says Not running or Degraded

Work through these in order:

The background service is not running

agenshield status ends in Status: ✗ Not running.

agenshield start

If it will not stay running, agenshield doctor reports why.

The macOS approvals were never granted

The report is ⚠ Degraded with the Enforcement checklist showing not approved rows — the most common cause on a Mac that is not MDM-managed. Run:

agenshield activate

and grant all three — system extensions, Full Disk Access, and network filtering. What gets installed walks through each one.

The device is not enrolled

The report is ○ Running, not enrolled — the software runs but no organization policy has been received. Re-run the install link from your administrator, or sign in from the AgenShield menubar.

An extension shows as not active

macOS will not enable a system extension without explicit approval.

Situation	What to do
Unmanaged Mac	System Settings → General → Login Items & Extensions, approve both AgenShield extensions
MDM-managed Mac	Either the configuration profile did not land (check the device in your MDM console), or the MDM System Extensions policy blocks AgenShield outright — see Extension approval never appears
Approved but inactive	A stale version from a previous release may be blocking it: agenshield doctor --cleanup-extensions, then restart
Recently upgraded	macOS finalizes extension changes on reboot — restart the Mac and re-check

Protection is on, but nothing is being enforced

Almost always Full Disk Access. Without it the security extension cannot evaluate file access, and it stays inert even though it looks approved.

System Settings → Privacy & Security → Full Disk Access → enable the AgenShield security extension, then restart the Mac.

If enforcement is still not happening, check whether your organization is in monitor mode — in monitor nothing is blocked by design. See Enforcement modes.

Network rules have no effect

The “Filter Network Content” prompt was dismissed. Re-run agenshield activate and approve it, or approve the AgenShield network extension in System Settings → Network → Filters.

If your organization has enabled traffic inspection, also confirm the inspection certificate is present and trusted — see Network inspection certificate.

Policy is stale or never synced

The Mac cannot reach your organization’s AgenShield backend.

1. Confirm general connectivity, then check for a proxy or VPN that blocks it.
2. agenshield logs shows the sync attempts and the error.
3. If the Mac was never enrolled, re-run the install link from your administrator.

Protection continues on the last policy received while offline — a stale policy is a visibility problem, not an unprotected machine.

Something my agent needs is being blocked

Expected when your organization is in audit or enforce. Do not work around it: every block is recorded with the rule that caused it, and that record is what gets the policy fixed.

Send your administrator what you were doing, roughly when, and the error the agent reported. See Working with your agents.

AgenShield says enforcement is paused

The security extension carries a safety circuit-breaker: if it restarts several times in a short window it stands itself down rather than risk making the Mac unusable. AgenShield is then installed and running but not enforcing.

See Enforcement paused for how to confirm it and restore enforcement.

Status says Boot-locked

The background service failed repeatedly and has parked itself rather than crash-looping. Enforcement continues on the last signed policy — the Mac is not unprotected.

agenshield doctor

The Mac is slow or unresponsive

Not expected — decisions are cached and should be unnoticeable.

If the machine is badly degraded, boot into Safe Mode, where third-party system extensions do not load and the Mac becomes usable again:

Shut down, hold the power button until “Loading startup options” appears, select the disk, hold Shift, and choose Continue in Safe Mode.

Then collect a diagnostics bundle before uninstalling — uninstalling removes the evidence.

If the machine is responsive but the network feels slow, that is a different problem with a different answer — see Network Feels Slower.

AgenShield is writing a lot to disk

Versions 2026.7.22 and earlier recorded activity to disk far less efficiently than intended, which on a machine running an active agent produced sustained background disk writes. macOS notes this internally but does not act on it, so there is no error, no alert, and nothing stops working — the only real cost is unnecessary wear on the SSD and some battery on laptops.

Fixed in 2026.7.23, which reduced the write volume by roughly 5x. If you are on an older build, upgrade:

agenshield upgrade
agenshield status --install    # confirm the version actually installed

There is nothing to clean up afterwards and no data is affected — the stored activity history is unchanged either way.

The installer says the device is already registered

On an MDM-managed Mac, versions 2026.7.24 and earlier can print this during an install or upgrade:

⚠ Device already registered on the cloud side
  This device is already enrolled on the cloud but local credentials are missing

On a managed Mac this message is almost always spurious: the enrollment token is re-supplied automatically on every run, and the device is in fact enrolled and healthy. Check before acting:

agenshield status

If it reports connected and enrolled, no action is needed — ignore the banner and continue.

Do not follow the older banner’s suggestion to re-run with --force, and do not deregister the device from the Frontegg Portal, unless agenshield status actually shows cloud sync broken. On a healthy device, forcing re-registration desyncs its identity and the only recovery is uninstall and reinstall.

Newer releases no longer print the message when the device is already enrolled, and the remedy text leads with the status check instead of --force.

After an upgrade something broke

agenshield status --install    # what version is actually installed
agenshield doctor

If the upgrade summary listed warnings, or the app’s Updates card shows Action needed, start with what those name — they are written from the verification the upgrade just ran.

macOS finalizes system-extension changes on reboot, so an upgrade often needs one restart before everything reports healthy.

Still stuck

Collect a diagnostics bundle and send it to support with what you were doing, when it started, whether it followed an upgrade, and the output of agenshield status.