AgentWatch

Appearance

Troubleshooting ​

Common Issues ​

401 Unauthorized ​

Symptom: All API calls return 401.

Causes:

  1. Missing Authorization header
  2. Wrong token format (must be Bearer aw_live_xxx, not Token aw_live_xxx)
  3. Token not in TENANT_TOKEN_MAP or KV store

Fix:

python
# Correct format
client = WatchedOpenAI(
    agentwatch_api_key="aw_live_xxx",  # Must start with aw_
    ...
)

Budget Check Always Passes ​

Symptom: AgentBudgetExceeded is never raised even when spending exceeds the limit.

Causes:

  1. agentwatch_enforcement_mode is False (default)
  2. agentwatch_session_budget_usd is not set
  3. Session ID is not consistent across calls

Fix:

python
client = WatchedOpenAI(
    agentwatch_enforcement_mode=True,  # Must be True
    agentwatch_session_budget_usd=2.00,  # Must be set
    agentwatch_session_id="consistent-id",  # Must be consistent
    ...
)

AgentWatch Outage Affecting Production ​

Symptom: API calls fail when AgentWatch is down.

Cause: Using proxy mode (agentwatch_primary_provider) without failover.

Fix:

python
# Option 1: Use SDK-only mode (recommended)
client = WatchedOpenAI(
    agentwatch_api_key="aw_live_xxx",
    # No agentwatch_primary_provider — calls go directly to OpenAI
)

# Option 2: Enable failover
client = WatchedOpenAI(
    agentwatch_primary_provider="openai",
    agentwatch_fallback_provider="anthropic",
    ...
)

Streaming Calls Not Counting Toward Budget ​

Symptom: Streaming calls bypass budget enforcement.

Cause: Token counts are unavailable until stream completion. Budget enforcement uses estimated counts.

Fix: This is expected behavior. Use non-streaming calls for strict budget enforcement.

Rate Limiting (429) ​

Symptom: Requests return 429 Too Many Requests.

Cause: Exceeded 100 requests per minute per tenant.

Fix:

  • Reduce request frequency
  • Contact support to increase limits
  • Use batch APIs where available

Telemetry Not Appearing ​

Symptom: Logs don't appear in Supabase dashboard.

Causes:

  1. SUPABASE_URL or SUPABASE_SERVICE_ROLE_KEY not configured
  2. Queue consumer not running
  3. 90-day retention purged old logs

Fix: Check Worker logs for Supabase connection errors.

Performance Issues ​

Slow Budget Checks ​

Budget checks involve a network round-trip to Cloudflare KV (5-50ms). If consistently slow:

  1. Check Cloudflare status page
  2. Verify Worker is deployed to the correct region
  3. Consider using Durable Objects for atomic operations

High Latency on First Request ​

First requests may be slower due to Worker cold start (V8 compilation). Subsequent requests are fast.

Getting Help ​

  • Email: mohil.sharma@agent-watch.dev
  • Health Check: curl https://agent-watch.dev/healthz