🛠️ AI Gateway Troubleshooting

Use this guide for AI Pilot issues in Settings -> AI Pilot.

📌 Quick triage

1. Confirm the selected environment (Sandbox vs Production).
2. Confirm the selected bouncer is Active and receiving heartbeats.
3. Check that AI Gateway settings are saved (global or local override as expected).
4. Inspect Forensics and Trace Log for deny/failure reasons.

🛠️ Common issues

No AI Gateway data appears

• Verify bouncer connectivity in Settings -> PEPs.
• Use the refresh actions and observability sections in Settings -> AI Pilot.
• Confirm bouncer health URL is set and reachable by Control Plane.

Settings save fails

• Validate numeric fields (tokens, burst, window, cache TTL) are positive.
• If using local override, ensure required sections are populated.
• Retry after refreshing bouncer status.

Unexpected denies or over-blocking

• Review harm threshold and violation action.
• Start with redact in sandbox for tuning, then move to block where needed.
• Check trace reasons to identify prompt-shield or policy causes.

Missing forensics traces

• Confirm traffic actually passes through the selected bouncer.
• Confirm environment selection matches where tests were run.
• Increase time window (for example 24h or 7d).

High latency or cost spikes

• Tighten tokens/min and burst settings.
• Enable prompt caching and increase cache TTL for repetitive prompts.
• Use trace log and observability cards to identify hot paths.

📌 Escalation data to collect

When opening an incident ticket, include:

• Environment and bouncer name
• Time window and timezone
• Screenshots of AI Pilot forensics summary
• 5-10 representative trace log entries
• Current baseline mode (global/local) and key thresholds