Troubleshooting

Solutions for the most common Agent Identity Security problems, organized by area, followed by frequently asked questions about how Agent Identity Security works. This topic covers product-wide issues. If you are troubleshooting a specific Guardian installation (Claude Code, Cursor, GitHub Copilot CLI, and so on), refer to the troubleshooting topic at the end of each coding agent installation guide.

Agents not appearing in Registry

Problem	Likely cause	What to do
Registry shows no agents immediately after connecting an integration	Agent Identity Security runs discovery on a schedule. No agents have started a session since the integration was connected.	Wait up to 15 minutes, then trigger agent activity on the connected platform (for example, open a Copilot Studio agent or run a Claude Code session). Refresh the Agents page.
Non-coding agent platform connected but agents never appear	Incorrect Tenant ID, wrong API credentials, or insufficient platform permissions.	Go to Integrations, select the integration, and select Test Connection. If the test fails, re-enter your credentials. Confirm that the service account used has read access to agents and sessions on the platform.
Some agents visible but others are missing	Platform-side visibility restrictions — the Agent Identity Security service account can only see agents it has permission to read.	On the AI platform, confirm that the Agent Identity Security service account or API key has access to all agent environments, not just the default one. For Copilot Studio and Power Platform, this means access to each environment independently.
Agent count drops suddenly between sessions	Platform-side deletion, an integration credential that has expired, or a sync error.	Check Govern > Event Logs for sync error events. Go to the integration settings and select Test Connection to confirm credentials are still valid. If they have expired, re-authenticate and wait for the next sync.

Guardian silent or not reporting

Problem	Likely cause	What to do
Guardian installed but no agent sessions appear in Registry or Event Logs	API key is missing the agent_discovery:write scope, or the machine cannot reach the Agent Identity Security server.	Go to Settings > API Keys and confirm all three required scopes are present: agent_discovery:write, audit_logs:write, and policy:read. Verify network connectivity from the workstation to the Agent Identity Security server URL. Re-run the Guardian installer to apply the corrected key.
Event Logs show sessions but audit data is missing	API key is missing the audit_logs:write scope.	Re-create the API key with the audit_logs:write scope and re-run the Guardian installer on the affected workstation.
Guardian reports intermittently — sessions drop in and out	Unstable network connection between the workstation and the Agent Identity Security server.	Check for proxy or firewall rules that may be interrupting the connection. Ensure the Agent Identity Security server hostname resolves correctly and that the workstation can reach it on port 443. Review your network team’s allowlist if using an enterprise proxy.
Guardian is running but policies are not enforced	API key is missing the policy:read scope.	Edit or re-create the API key to include policy:read and re-run the installer. Confirm the policy is set to Active in Secure > Access Policies.
Uninstalled Guardian but agent still appears in Registry	Agent Identity Security retains historical agent records. Uninstalling the Guardian stops new data but does not purge existing records.	This is expected behavior. The agent record will remain until it is manually deleted from the Agents page or until it ages out of the retention window configured for your tenant.

Policy not triggering as expected

Problem	Likely cause	What to do
Policy shows Active but is not blocking the connection	Resource match value does not match the exact server name or URL the agent is using.	In Govern > Event Logs, find a recent event for the connection and copy the exact resource value from the event detail. Use that value as the Resource Match in the policy rule. Wildcard matching (*.example.com) is supported for MCP resource types.
Policy targets the correct resource but applies to too many agents	The Agents field in the policy is set to All Agents instead of a specific agent.	Edit the policy and select the specific agent or agents the rule should apply to. If you need the policy to apply across a platform, use the Platform field to scope it rather than leaving Agents open.
Approval notifications are not arriving in Slack	The Slack HITL (Human-in-the-Loop) integration is not connected, or the channel ID is incorrect.	Go to Integrations and confirm the Slack integration status is Connected. Verify the notification channel ID in the integration settings. Ensure the Agent Identity Security Slack app has been invited to that channel with /invite @Agent Identity Security.
Policy enforces during business hours only but is blocking outside those hours	Enforcement schedule uses the Agent Identity Security server timezone, not the agent’s local timezone.	In the policy enforcement schedule, confirm the times match the Agent Identity Security server timezone shown in Settings > General. Adjust the schedule to account for timezone differences if your agents operate in a different region.
Deleted a policy but the agent is still blocked	A second policy targeting the same resource is still active.	Go to Secure > Access Policies and filter by the resource type and agent. Check for any remaining policies that include a Block rule for the same resource match.

MCP Gateway connection issues

Problem	Likely cause	What to do
Agent reports connection errors after pointing it at the gateway endpoint	The endpoint status is Disabled, or the upstream MCP server URL is incorrect.	In Secure > MCP Gateway, confirm the endpoint status is Active. Verify the target server URL by connecting to it directly from your network before adding it to the gateway.
Agent connects through the gateway but tool calls are slower than direct	Expected behavior — the gateway adds a proxy hop and runs content inspection.	This latency is inherent to proxied, inspected traffic. If latency exceeds acceptable limits, review the content scanning rules configured for the endpoint and disable any that are not required for this server.
Gateway endpoint shows Active but no traffic appears in Event Logs	The AI client is not using the proxied URL — it is still connecting directly to the upstream server.	Confirm the AI client configuration has been updated to use the Agent Identity Security gateway URL, not the original server URL. For MCP clients, this typically means updating the mcp_servers config to point to the gateway endpoint.

Authentication and access issues

Problem	Likely cause	What to do
Cannot log in — SSO page shows an error	SSO configuration is incomplete, the redirect URI does not match, or your identity provider session has expired.	Clear your browser cache and try again. If the error persists, contact your Agent Identity Security administrator to confirm the SSO configuration (client ID, redirect URI, and issuer URL) matches the identity provider settings exactly.
Logged in but cannot see a page that should be visible	Your Agent Identity Security role does not include permission for that section.	Ask your Agent Identity Security administrator to review your role assignment in Settings > Users. The Security Analyst role provides read access to Registry and Govern. The Administrator role is required for Secure, Settings, and Integrations.
API key was generated but Agent Identity Security says it is invalid	The key was not copied correctly at generation time, or it has been revoked.	Agent Identity Security displays the API key only once at creation. If the key was not saved, delete it and generate a new one. Confirm there are no leading or trailing spaces when pasting the key into the Guardian installer or integration configuration.

For answers to common questions about risk scores, data retention, policies, and API keys, see Frequently Asked Questions.