DocumentationAgent Action Firewall
GitHub

Troubleshooting

Common issues and solutions when working with Agent Action Firewall.

Authentication Issues

401 Unauthorized

Symptom: API returns 401 error

Possible causes:

  • Invalid or expired API key
  • Missing Authorization header
  • API key doesn't have required permissions

Solution:

TypeScript
// Ensure your API key is correctly set
const client = new AgentFirewallClient({
  apiKey: process.env.AGENT_FIREWALL_API_KEY, // Check this is defined
  // ...
});

// Verify the header format
// X-Agent-Key: YOUR_API_KEY

403 Forbidden

Symptom: API returns 403 error

Possible causes:

  • API key lacks permission for this resource
  • Agent ID not authorized for this organization
  • IP address not in allowlist (if configured)

Policy Issues

Actions Always Denied

Symptom: All actions return "denied" status

Possible causes:

  • No allow policies configured
  • Policy syntax error preventing evaluation
  • Default deny without matching allow rules

Solution:

  1. Check your policies in the dashboard
  2. Use the policy simulator to test
  3. Verify policy syntax with the Rego validator
Bash
# Test your policy
curl -X POST https://api.agentactionfirewall.com/admin/policies/:id/simulate \
  -H "Authorization: Bearer $SUPABASE_JWT" \
  -d '{"input": {"action": {"tool": "http_proxy", "operation": "GET"}}}'

Policy Not Applying

Symptom: Policy changes don't seem to take effect

Possible causes:

  • Higher priority policy is matching first
  • Policy is inactive
  • Cache delay (policies update within 30 seconds)

Approval Issues

Approvals Timing Out

Symptom: Approval requests expire before being handled

Solutions:

  • Increase approval timeout in Settings
  • Configure notification channels (Slack, email)
  • Set up escalation rules

Not Receiving Notifications

Symptom: Approval requests not appearing in Slack/email

Check:

  • Integration is connected and active
  • Correct channel/recipients configured
  • Bot has permission to post in channel

SDK Issues

Connection Timeout

Symptom: Requests timeout before completing

TypeScript
// Increase timeout
const client = new AgentFirewallClient({
  timeout: 60000, // 60 seconds
  // ...
});

TypeScript Errors

Symptom: Type errors when using the SDK

Solution: Ensure you're using TypeScript 5.0+ and the latest SDK version

Bash
pnpm add @agent-action-firewall/sdk@latest

Rate Limiting

429 Too Many Requests

Symptom: API returns 429 error

Rate limits:

  • Actions: 100 requests/minute
  • Admin: 50 requests/minute

Solution:

TypeScript
// Implement exponential backoff
async function submitWithRetry(action, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await client.submitAction(action);
    } catch (error) {
      if (error.status === 429 && i < maxRetries - 1) {
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      throw error;
    }
  }
}

Debug Mode

Enable debug logging for detailed troubleshooting:

TypeScript
const client = new AgentFirewallClient({
  debug: true, // Enables detailed logging
  // ...
});

Getting Help