Skip to main content

​
Agent is unreachable

Symptoms: Admin overview shows “Agent unreachable”. API calls to create/delete databases fail.
1

Check the agent service

ssh ubuntu@13.61.204.171
sudo systemctl status db-agent
If it’s not running, check logs:
sudo journalctl -u db-agent -n 50 --no-pager
2

Check Caddy

sudo systemctl status caddy
curl -v https://agent.dbhost.app/health
3

Check DNS

dig agent.dbhost.app
Should resolve to 13.61.204.171.

​
Database creation fails

Symptoms: “Agent responded with 500” or “INTERNAL_ERROR”. Common causes:
  • PostgreSQL is down: sudo systemctl status postgresql
  • Disk full: df -h
  • Database name already exists at the Postgres level but not in the app DB (orphaned)

​
PgBouncer connection refused

Symptoms: Clients can’t connect on port 6432. 
# Check PgBouncer status
sudo systemctl status pgbouncer

# Check if it's listening
ss -tlnp | grep 6432

# Check PgBouncer logs
sudo journalctl -u pgbouncer -n 50
Common causes:
  • PgBouncer config syntax error (check after agent edits)
  • Max connections reached: connect to pgbouncer admin and run SHOW POOLS;

​
Migration fails

Symptoms: drizzle-kit migrate errors. 
# drizzle-kit doesn't read .env.local — pass DATABASE_URL explicitly
DATABASE_URL="postgresql://..." npm run db:migrate
If using PgBouncer (port 6432), most migrations work fine. If you hit prepared statement issues, connect directly to PostgreSQL (port 5432) via SSH tunnel: 
ssh -fN -L 5433:localhost:5432 ubuntu@13.61.204.171
DATABASE_URL="postgresql://postgres:password@localhost:5433/dbhost" npm run db:migrate

​
Clerk webhook not firing

Symptoms: Users sign up but don’t appear in the users table.
  1. Check CLERK_WEBHOOK_SECRET is set in Vercel env vars
  2. Verify webhook URL in Clerk dashboard points to https://dbhost.app/api/webhooks/clerk
  3. Check Clerk dashboard webhook logs for delivery failures
  4. The ensureUser() function in the dashboard layout is a fallback — users are created on first page load even without webhooks
Symptoms: You signed in but don’t see “Admin” in the sidebar. Your user record needs the admin role: 
DATABASE_URL="postgresql://..." npx tsx scripts/promote-admin.ts <your-clerk-user-id>
Then refresh the page (hard refresh: Cmd+Shift+R).