Troubleshooting
Common issues, diagnostics, and resolution steps.
Troubleshooting
Overview
Common issues and fixes when integrating, deploying, and operating AgentTrust.
Why It Matters
Fast diagnosis reduces downtime and prevents silent governance bypass.
Prerequisites
agentrust statusandagentrust whoamiavailable- Gateway logs accessible
Step-by-Step Guide
SDK issues
| Symptom | Cause | Fix |
|---|---|---|
| Decorator is no-op | AGENTRUST_ENABLED=false | Set to true, or it is an intentional kill-switch |
| Calls succeed but nothing is governed or audited | Gateway unreachable under the default fail-open mode | Set AGENTRUST_FAILURE_MODE=closed to make the failure loud, then fix the URL |
user="unknown" in every envelope | Agent called with positional args | Call with keyword arguments, or set user_kwarg / input_kwarg |
GatewayUnavailableError | Gateway down + closed mode | Fix gateway or set failure_mode=open |
BlockedError on all calls | Policy too strict | Review e.reason and validation.failures; adjust the policy pack |
TierGateError | Feature above tier | Upgrade or remove tier-gated adapter |
GatewayVersionError | SDK/gateway mismatch | Upgrade both to compatible versions |
| Auto-instrument not working | Import order | Call auto_instrument() before framework imports |
| No audit records | Wrong gateway URL, or fail-open masking an outage | Verify AGENTRUST_GATEWAY_URL, then curl $AGENTRUST_GATEWAY_URL/health |
| Queue not draining | Gateway still down | agentrust queue replay when reachable |
Gateway issues
| Symptom | Cause | Fix |
|---|---|---|
| 401 Unauthorized | Invalid/missing token | Check AGENTRUST_KEY and AGENTRUST_API_KEYS |
| 403 Forbidden | Tier insufficient | Upgrade subscription |
| 503 Service Unavailable | Postgres/Redis down | curl /health; check compose logs |
| High latency | Redis unreachable | Verify REDIS_URL |
| Review queue empty | No escalate decisions | Check decision thresholds |
| Dashboard blank | CORS/API URL | Set VITE_API_URL to gateway |
Deployment issues
| Symptom | Cause | Fix |
|---|---|---|
| Port 8765 in use | Embedded conflict | AGENTRUST_EMBED_PORT=8766 |
| Migration errors | Multi-replica migrate | Run Alembic as K8s Job |
| Sidecar connection refused | Wrong port | Match sidecar port to env var |
Diagnostic commands
agentrust status
agentrust whoami
agentrust queue status
agentrust audit tail
curl http://localhost:8000/health
curl -H "X-AgentTrust-Token: $AGENTRUST_KEY" http://localhost:8000/v1/auth/checkEnable debug logging
import logging
logging.getLogger("agentrust_sdk").setLevel(logging.DEBUG)Examples
Test gateway connectivity:
from agentrust_sdk import AgentTrustClient
client = AgentTrustClient()
# First validate call will surface connection issuesBest Practices
- Run
agentrust whoamiafter any key change;curl $AGENTRUST_GATEWAY_URL/healthafter any URL change - Test failure modes in staging before production
- Monitor
/healthand/metricsendpoints - Keep SDK and gateway versions aligned
Common Mistakes
- Debugging without checking
AGENTRUST_ENABLEDfirst - Assuming embedded gateway has same behavior as full edge
- Using Python
AGENTRUST_KEYin Node.js (useAGENTRUST_API_KEY)