TROUBLESHOOTING
COMMON ISSUES AND HOW TO FIX THEM
Solutions for the most common issues you may encounter with Shield agents, alarms, alerts, and the MCP Scanner.
AGENT NOT CONNECTING
The agent is installed but does not appear in the Shield Dashboard. It cannot reach the Shield API.
CHECK API KEY
Verify that the API key configured in the agent matches the key shown in your Shield Dashboard Settings page. Copy the key again and ensure there is no trailing whitespace or newline. The key is case-sensitive.
CHECK NETWORK
The agent needs outbound HTTPS access to api.agentdefenders.ai on port 443. Test connectivity with: curl -v https://api.agentdefenders.ai/healthz -- you should get a 200 response. If you are behind a corporate proxy, configure the HTTPS_PROXY environment variable.
CHECK FIREWALL
If you are running on a cloud VM, check that the security group or firewall rules allow outbound traffic on port 443. Some cloud providers block all outbound traffic by default. Also check host-level firewalls (iptables, ufw, firewalld).
CHECK AGENT LOGS
The agent writes logs to its data directory. Check the log file for connection errors, authentication failures, or TLS handshake issues. The log file location is printed during installation.
AGENT SHOWING AS OFFLINE
The agent previously connected but now shows as offline in the dashboard. This means the Shield API has not received a heartbeat within the expected interval.
HEARTBEAT INTERVAL
The agent sends a heartbeat every 30 seconds. The dashboard marks an agent as offline after 3 missed heartbeats (90 seconds without contact). Temporary network interruptions may cause brief offline periods that resolve automatically.
CHECK PROCESS IS RUNNING
Verify the agent process is still running on the host machine. Check your process list for the agent binary. If the process has stopped, check the agent logs for the exit reason and restart it. If the host rebooted, ensure the agent is configured to start on boot (the installer sets this up automatically on systemd-based systems).
ALARMS NOT DEPLOYING
The agent is connected but alarms are not deploying or showing as inactive in the dashboard.
CHECK AGENT VERSION
Make sure you are running the latest version of the Shield agent. Older versions may not support all alarm types. Run the installer again to update to the latest version -- it will preserve your existing configuration.
CHECK PROJECT CONFIG
For OpenClaw Shield, alarms deploy automatically when the agent detects an OpenClaw installation. If alarms are not deploying, the agent may not be finding your OpenClaw data directory. Ensure the agent runs as a user with read access to the OpenClaw configuration and data files. Check the agent logs for discovery-related messages.
ALERTS NOT ARRIVING
Alarms are deployed and the dashboard shows events, but you are not receiving alerts through your configured channels.
CHECK CHANNEL CONFIG
Go to Settings in the Shield Dashboard and verify your alert channels are configured correctly. For email, check that your email address is verified. For Slack, verify the webhook URL is correct and the Slack app has permission to post to the target channel. For Telegram, confirm the bot token and chat ID are correct. For webhooks, verify the endpoint URL is reachable from the internet.
CHECK RATE LIMITS
Alert channels have rate limits to prevent flooding. If many events fire in rapid succession, some alerts may be batched or deferred. Check the dashboard for the full event history -- all events are always recorded even if alert delivery is rate-limited. Rate limits reset automatically after a short cooldown period.
SCANNER NOT FINDING MCP CONFIGS
The MCP Scanner runs but reports no MCP servers found.
SUPPORTED CLIENTS
The scanner discovers MCP server configurations in VS Code, Cursor, Windsurf, and Claude Desktop. If you use a different client, the scanner may not know where to look for its configuration files. Check the scanner documentation for the full list of supported clients.
CONFIG PATHS
The scanner looks for MCP configuration in standard locations for each supported client. On macOS, these are typically in ~/Library/Application Support/. On Linux, they are in ~/.config/. If your client uses a non-standard configuration path, the scanner may not find it. Check the scanner output for the paths it searched.
GETTING HELP
If none of the above solutions resolve your issue, contact our support team. Include the following information to help us diagnose the problem faster:
- >Your operating system and version
- >Shield agent version (shown during installation and in agent logs)
- >Relevant agent log output (redact your API key)
- >Steps to reproduce the issue
Email us at support@agentdefenders.ai -- we typically respond within 24 hours on business days. Priority support is available on Pro and Plus tiers.
Still stuck? We are here to help.