Skip to the content

Troubleshooting

What you see when something goes wrong with AgentGarm, and the guide step that explains and fixes it, by symptom.

Installing and checking

Installing and checking: symptoms and where to fix them
What you seeWhere to go
agentgarm doctor reports a failed checkCheck that protection is on: Run doctor
agentgarm status shows the proxy NOT answeringCheck that protection is on: Check the services
agentgarm status says a policy is NOT LOADEDWatch your agent for a week, then enforce: Install the pack in audit mode
A session is rated C, or lower than you expectedCheck that protection is on: Read each session's assurance level
A bypass alert appearsCheck that protection is on: Act on a bypass alert
An agent's version is out of range or unknownKeep agent versions in check: Bring the agent back into range
A download's signature or checksum does not verifyCheck for and verify AgentGarm updates: Verify the download before you run it
agentgarm status says agentgarmd's binary was replaced on disk: restart agentgarmdCheck for and verify AgentGarm updates: Check that the new release is running

Launching an agent

Launching an agent: symptoms and where to fix them
What you seeWhere to go
agentgarm run refuses to launch because of the project's agent configurationCatch poisoned agent configs before launch: Let agentgarm run refuse a poisoned launch
The sandbox canary fails and the launch is refusedLimit what an agent can read, write and reach: Let the canary prove the sandbox
Claude Code says Not logged in under agentgarm runGovern Claude Code: Start Claude Code through agentgarm run
Codex makes no model call, or cannot save a folder's trust, under agentgarm runGovern Codex CLI: Start Codex through agentgarm run
A model call carrying a claude.ai or ChatGPT-plan login is refused with 403Give Claude Code a per-developer gateway key: Know why a subscription login is refused
A model call stops at the budget capSet spend budgets and stop runaway loops: Recognise the cap
A call is refused because the provider bills in another currency than the USD budgetSet spend budgets and stop runaway loops: Recognise the cap
An agent's WebSocket gets 426 Upgrade Required from the proxyGovern Codex CLI: Start Codex through agentgarm run

Decisions

Decisions: symptoms and where to fix them
What you seeWhere to go
A file read or write is deniedLimit what an agent can read, write and reach: Recognise a denial
A command is treated as opaque and asked about or deniedAllow, ask or deny shell commands: Know when a command is opaque
Enforcing would block everyday workWatch your agent for a week, then enforce: Fix the rules that would get in the way
A secret is flagged that is not oneKeep secrets and card numbers out of prompts: Deal with a false positive
You need an exception to a ruleTrace what one agent task did: Ask for an exception to a rule

Approvals

Approvals: symptoms and where to fix them
What you seeWhere to go
Every ask is denied after a fingerprint changeApprove risky actions with Touch ID: Re-enrol after a fingerprint change
No approval prompt appearsApprove risky actions with Touch ID: Keep the presence watcher running
A Mac with an enrolled key is lost, or its user leavesApprove risky actions with Touch ID: Replace or retire a key when a Mac is lost or a person leaves

Outbound inspection (preview)

Outbound inspection (preview): symptoms and where to fix them
What you seeWhere to go
A tool refuses AgentGarm's certificate, or a site shows Refused by toolCheck what agents upload to paste sites and webhooks: When a tool refuses the certificate
A task shows Restart to inspect, or a site newly in Block is refused for a running agentCheck what agents upload to paste sites and webhooks: Run an agent with agentgarm run
Certificates can't be issued: agentgarm inspect status says the web CA is unavailableCheck what agents upload to paste sites and webhooks: Turn it on

Computer use (macOS)

Computer use (macOS): symptoms and where to fix them
What you seeWhere to go
agentgarm run refuses: the computer-use posture needs a live airbagGovern computer-use agents: Install the airbag and grant it Accessibility
agentgarm doctor says the airbag lacks AccessibilityGovern computer-use agents: Install the airbag and grant it Accessibility
The airbag's Accessibility grant is lost after a rebuild or an updateGovern computer-use agents: Install the airbag and grant it Accessibility
agentgarm status shows a task SUSPENDED with an airbag holdGovern computer-use agents: See why a task was suspended, and get it going again
An allowed tool's clicks or key presses are droppedGovern computer-use agents: Read what would have been dropped, and open what you need
No agent shows a Screen Recording grant, or grants are unknownWatch what agents can capture: See which agents hold a grant

Sentinels, Windows, MCP tools and local runtimes (preview)

Sentinels, Windows, MCP tools and local runtimes (preview): symptoms and where to fix them
What you seeWhere to go
agentgarm status shows a macOS sentinel line as FAILTurn on the macOS sentinels: Check that the sentinels are connected
A security key stops approving on WindowsApprove risky actions on Windows: Re-enrol when a key stops working
A new or changed MCP tool is missing from the agent's list, or its calls are refusedContain prompt injection in MCP tool output: Approve a new or changed tool
An MCP tool is held back for a poisoned descriptionContain prompt injection in MCP tool output: See poisoned tool descriptions held back
agentgarm status --inventory lists a local runtime as UNMANAGEDSee the AI runtimes and desktop AI apps on a machine: Read unmanaged and governed

Fleet deployment (preview)

Fleet deployment (preview): symptoms and where to fix them
What you seeWhere to go
A force-installed browser extension never gets the machine's policyDeploy AgentGarm with MDM: Force-install the browser extension

Records and recovery

Records and recovery: symptoms and where to fix them
What you seeWhere to go
The audit chain does not verifyExport and verify the audit log: Read a broken chain
The dashboard refuses its launch code, or stops loadingTrace what one agent task did: Open the dashboard
An agent changed files you want backUndo what an agent changed: Preview the rollback, then apply it
Support asks for detailsSend a redacted support bundle: Write the bundle

Central Lite (preview)

Central Lite (preview): symptoms and where to fix them
What you seeWhere to go
An admin lost their passkeyStand up Central Lite: Recover an admin who lost their passkey
Central Lite cannot open its keys: a wrong PIN or another tokenKeep Central Lite's keys in a hardware security module: Know what a wrong PIN or another token does

Kill orders and evidence (preview)

Kill orders and evidence (preview): symptoms and where to fix them
What you seeWhere to go
Your agent stopped and won't start againFind out why your agent stopped: Tell a suspend, a kill, a lockdown and a budget breach apart
agentgarm status says this machine is locked downFind out why your agent stopped: See what happened
agentgarm status shows a task SUSPENDED with a breach or order holdFind out why your agent stopped: Ask who can lift it
A kill order won't be requested: too few approver keys countStop agents across a fleet: Set up approvers before you need them
A node answered a kill order refusedStop agents across a fleet: Read each node's answer
A node shows as too old, or never answers an orderStop agents across a fleet: Read each node's answer
Central Lite is down and an order must reach a machineStop agents across a fleet: Stop or lift by hand when Central Lite is down
A task's evidence bundle doesn't verifyExport evidence for one task: Verify it with the node's key
Central Lite refuses to export a task's evidence bundleInvestigate a task across the fleet: Export Central Lite's bundle, with its hold
Central Lite's evidence bundle doesn't verifyInvestigate a task across the fleet: Verify it offline against the org root

Single sign-on, SCIM and SIEM (preview)

Single sign-on, SCIM and SIEM (preview): symptoms and where to fix them
What you seeWhere to go
Sign-in refused: your identity is not linked to an active Central adminSign in to the console with your identity provider: Sign in, then add your passkey
Sign-in refused: the user is in too many groups for the token (Entra group overage)Sign in to the console with your identity provider: Map groups or app roles to console roles
Sign-in refused: the token is from another issuer (or tenant)Sign in to the console with your identity provider: Point Central Lite at your provider
The console is read-only after signing in with single sign-onSign in to the console with your identity provider: Sign in, then add your passkey
Passkey sign-in is refused: it is for owners while SSO is requiredSign in to the console with your identity provider: Require SSO and keep a break-glass owner
A console page says your roles don't allow thisGive people the right access in the console: Know the roles and what each sees
Your identity provider's SCIM requests get 401Provision and remove people with SCIM: Rotate the token
Your identity provider's SCIM requests get 429Provision and remove people with SCIM: Connect Okta or Entra ID
People your identity provider removed are still active: a wave was heldProvision and remove people with SCIM: Decide what to do with a held wave
A SIEM sink is stopped, or falls behind (siem_lag)Send the fleet's security events to Splunk or Sentinel: Read lag, rejects and gaps
A SIEM sink recorded a gap, or rejects eventsSend the fleet's security events to Splunk or Sentinel: Read lag, rejects and gaps
SIEM sinks stopped after a restore: credential not in this Central's keystoreSend the fleet's security events to Splunk or Sentinel: Rotate a credential

Still stuck

Write a support bundle (the support bundle guide): it leaves secrets and prompt text out. Then email support@nannertech.com with what you ran and what you saw.