Troubleshooting

Common issues when deploying and running Shadow AI, and how to resolve them. For directory-sync issues specifically, see Directory Integration → Troubleshooting.

A device doesn't appear under Devices

A client only shows up after it enrolls and checks in. Verify:

• Keys are present. The client needs valid project keys. If you used the enrollment script, confirm it ran for the logged-in user (not a different/admin account). If you used MDM, confirm the credential policy applied.
• The client launched after keys were seeded. Relaunch the browser / agent so it picks up the seeded keys.
• Network reachability. The client must be able to reach your AgenticAnts host over HTTPS. Check proxies / firewalls.

A device shows Degraded

Degraded means the client is online but reporting issues. Open the device detail panel (click the row under Devices) and check the recent check-in timeline for the reason — common causes:

• Missing permissions (macOS). The agent needs Accessibility and Full Disk Access, and its system extensions approved, in System Settings. Until granted, collectors run degraded. The Settings → Overview page shows permission coverage across the fleet.
• Version drift. A very old client version — update it (MDM-managed installs update silently).
• Upload failures. Usually transient network issues; they clear on the next successful check-in.

A device shows Offline

No recent heartbeat. The machine may be powered off or off-network, or the agent/extension may have been removed or disabled. If it's online and still offline in the dashboard, treat it like "doesn't appear" above (keys, relaunch, network).

The browser extension won't enroll (icon not green)

• Confirm enrollment. For self-serve installs, open the extension and complete the enrollment step; the toolbar icon turns green when connected. Pin the icon so you can see its state.
• Keys not seeded. If you rely on the enrollment script or MDM credential policy, confirm it applied for this browser, then restart the browser.
• Wrong browser policy. For MDM, make sure you pushed both the force-install policy and the credential (3rdparty) policy for the correct browser (Chrome vs. Edge vs. Firefox use different IDs and policy paths).

No data after install, even though the device is Healthy

• Generate activity. Data appears only after the user actually uses an AI tool. Open ChatGPT/Claude.ai, run a prompt in Cursor/Claude Code, etc.
• Give it a minute. Events batch and ingest within a minute or two.
• Tool not recognized? If a tool you use isn't showing up, it may not be in the registry. Add it as an internal AI tool (private tools) or nominate it (public tools).
• Check the surface. A CLI tool reports via the desktop agent, a website via the browser extension, and coding agents via OTel telemetry — make sure the matching client is deployed on that device.

Clients suddenly return 401 / stopped reporting

This usually follows a key change:

• Immediate rotation or revoke-all invalidates old keys at once — every client 401s until it picks up the new keys. Re-deploy the new keys (push the updated MDM credential policy, or re-run the enrollment script).
• Prefer graceful rotation (7-day overlap) for routine rotation to avoid fleet disruption. See Project keys.

Coding-agent telemetry isn't arriving

See the dedicated checks in Coding Agent Telemetry → Troubleshooting — verify the environment variables / config are set, the endpoint is reachable (an unauthenticated POST should return 401, not 404), and the keys belong to the right project.

Still stuck?

Related

• Deploying Agents & Extensions
• Directory Integration
• Data & Privacy