Troubleshooting overview

If a thing doesn't work, the symptom usually maps to one of these areas. Each links to a dedicated page.

Symptom	Where to look first
"I'm getting 401/403 on admin endpoints"	Auth and RBAC
"OAuth callback fails / browser drops cookie"	OAuth
"Stripe webhook signature mismatch"	Stripe
"Subscription not updating after checkout"	Stripe
"Migration fails on prod"	Migrations
"My new agent doesn't show in the catalog"	Agent not appearing
"CORS error in the browser console"	CORS and cookies
"Quota consume returns 402 unexpectedly"	Auth and RBAC

First five things to check

Before going deep, always:

1. Find the requestId — every error envelope includes one. Use it to cross-reference PostHog and CloudWatch.
2. Check the actual response body, not just the status. Browser DevTools → Network → response.
3. Check the audit log — PostHog event = api_request AND requestId = '<uuid>'.
4. Check the env vars on the target environment. A 500 on prod with "Stripe configuration missing" probably means STRIPE_SECRET_KEY isn't set there.
5. Diff against a working environment. If dev works and prod doesn't, the gap is usually env vars, CORS allow-list, cookie config, or DNS.

Filing a bug

When you can't resolve it:

• The requestId is the single most useful piece of context. Paste it first.
• Include the request method, URL, and response status.
• Include the relevant error.code and error.message.
• Include browser/CLI/SDK version.
• Don't paste secrets.

[bug] Subscription checkout returns 422 INVALID_RETURN_URL
requestId: 550e8400-e29b-41d4-a716-446655440000
POST /agents/ag_xxx/pricing/tier_yyy/checkout
returnUrl: https://staging.app.my-agent.com/post-checkout
Expected: 200
Actual: 422 { error.code: INVALID_RETURN_URL, message: ... }