Skip to content

Troubleshooting

Agents are missing

  1. Confirm events are arriving:

bash curl -X POST http://localhost:8000/api/v1/ingest/events \ -H "X-API-Key: $API_KEY" \ -H "Content-Type: application/json" \ -d '{"agent_id":"test-agent","event_type":"task_completed","cost_usd":0.01,"business_value":1,"time_saved_minutes":5}'

  1. For AegisAI sync:

bash export AEGISAI_API_URL=https://aegisai.example/api/v1 export AEGISAI_API_KEY=... python scripts/migrate_aegisai_data.py

See also: Integration.

Metrics are empty / not updating

bash docker compose logs api --tail 100 curl http://localhost:8000/api/v1/health/ready

  • Make sure period covers your event dates (week / month).
  • If Redis is down, readiness fails (database/redis flags).
  • After bulk ingest, cache TTL is about 30 seconds.
  • Paid-plan features return 402 if subscription is not active/trialing — check Settings → Billing.

Cannot log in

  • Email must be a valid address (not .local) — demo: admin@example.com.
  • To reset admin data: recreate the DB volume (docker compose down -v — deletes data) or re-seed.
  • Google SSO: tenant must list the user's email domain under Users → Organizations (allowed_email_domains). Unknown domains are rejected.
  • SSO never creates super_admin users — platform admins stay password/bootstrap only.

Billing / 402 Payment Required

  • Free plan: ROI/compare/reports and >1 agent are blocked.
  • Pro/Business without live Stripe status behave as Free.
  • Portal needs stripe_customer_id (complete Checkout once first).

Deploy / migration failed

  • Pre-migrate backup failure aborts deploy — fix Postgres container, then retry.
  • Stale Alembic image: deploy.sh builds API before migrate; ensure IMAGE_TAG matches the commit with new revisions.
  • Check deploy.log and VERSION / GET /api/v1/version.
  • Rollback: ./scripts/rollback.sh --sha $(cat VERSION.prev).

Custom domain not resolving

Saving Settings → Domain only stores tenants.custom_domain. Point DNS and add Traefik/LE routes manually — see Deploy.

Rebuild the frontend container:

bash docker compose up -d --build frontend

Lockfile / CI

bash ./scripts/check_lockfile.sh uv pip compile requirements.txt -o requirements-lock.txt

Coverage below 55% fails CI — open the coverage-html artifact from the workflow run.