Troubleshooting Guide

Common issues and remediations. Fuller script notes: ../scripts/README.md.

Startup and environment

Login and IAM

Gateway and models

Policy and audit

SSO

Runbooks: sso-oidc-setup.md · sso-saml-setup.md

Vercel split deployment

Checklist: deployment/vercel-env-checklist.md

E2E / visual

Log locations

Database migrations

db:migrate fails with almost no error in the terminal

Symptom: pnpm --filter @agenticx/db-schema db:migrate or bootstrap.sh exits at the migrate stage with

Exit status 1 / ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL. The terminal only shows a one-line failure summary — no concrete SQL error.

If the log stops here:

1postgres is ready
2running db:migrate
3...
4ERR_PNPM_RECURSIVE_RUN_FIRST_FAIL ... drizzle-kit migrate

Docker and Postgres are already up; the failure is the database migration. Do not keep re-running bootstrap.sh. Get the underlying error first.

Step 1: Read the on-disk script logs

1cd enterprise
2ls -lt .runtime/logs/
3tail -n 120 .runtime/logs/bootstrap-*.log
4tail -n 120 .runtime/logs/db-migrate-*.log 2>/dev/null || true
5docker logs --tail=120 agenticx-postgres-dev

The terminal summary is not the root cause. The real PostgreSQL error is usually in .runtime/logs/bootstrap-*.log, db-migrate-*.log, or the Postgres container logs.

Step 2: Check whether you only removed the image, not the database

Docker images and Postgres data volumes are different things. After docker rmi or “clear images”, old database data usually remains in the Docker volume. Old tables, half-finished migrations, or old migration records can still make db:migrate fail.

If a development / POC environment can wipe the database, take the rebuild path:

1cd enterprise
2bash scripts/bootstrap.sh --reset-db
3bash scripts/start-dev-with-infra.sh --ui=stream

--reset-db deletes the local Postgres data volume and recreates the database. Do not use this in environments that must keep data.

Step 3: When you cannot wipe the database, keep the scene and keep investigating

1cd enterprise
2docker ps
3docker exec -it agenticx-postgres-dev psql -U postgres -d agenticx -c '\dt'
4docker exec -it agenticx-postgres-dev psql -U postgres -d agenticx -c 'select * from drizzle.__drizzle_migrations order by created_at desc limit 5;'

If drizzle.__drizzle_migrations is missing or the schema does not match expectations, send the output together with the logs.

Step 4: Check for concurrent migrations

If you see many CREATE TABLE waiting or too many clients already at the same time, see the PostgreSQL DDL lock-wait Runbook. This is usually multiple processes / replicas running migrations at once, not normal application traffic.

Getting help

1. Confirm DATABASE_URL points at the expected database (especially since reset scripts echo the URL)
2. curl --noproxy '*' http://127.0.0.1:8088/healthz
3. Admin GET /api/gateway/health
4. Gateway process logs (--ui=stream mode)

Made-with: Damon Li