Troubleshooting

Common errors and how to fix them.

Connection Errors

Error	Cause	Fix
Connection timeout	IP not whitelisted	Ask admin to whitelist your API server IP
`ECONNREFUSED`	DNS wrong or service down	Check `dig db.bizfylabs.com` and `docker compose ps`
Password auth failed	Wrong credentials	Verify connection pack; check user exists
Database does not exist	Not provisioned yet	Request admin to create DB/user
Qdrant 403	Missing API key	Set `QDRANT_API_KEY` header
Redis NOAUTH	Missing password	Include password in `REDIS_URL`
Too many connections	No pooling	Use connection pool; close sessions

Test from the Right Machine

Connections only work from the whitelisted API server (72.60.223.44). Your laptop will timeout unless you SSH tunnel through the API server.

# On API server — should succeed
nc -zv db.bizfylabs.com 5432
nc -zv db.bizfylabs.com 6379

# SSH tunnel from laptop
ssh user@72.60.223.44 -L 5432:db.bizfylabs.com:5432

Per-Database Issues

PostgreSQL

relation does not exist → run migrations in your API repo
permission denied → admin needs to grant table permissions

MongoDB

Shows unhealthy in Docker but works → health check timeout, not a real failure
not authorized → wrong authSource in URI

Redis

NOAUTH → password missing in connection URL
Keys disappearing → memory full, LRU evicting — add TTLs to cache keys

Qdrant

Vector dimension mismatch → collection size must match embedding model output
404 on collection → create it first via SDK

Neo4j

Slow first connection → JVM warmup, normal on cold start
Use db.bizfylabs.com not localhost

DNS Issues

dig +short db.bizfylabs.com A   # must return 72.60.97.82

NXDOMAIN → create A record in Hostinger DNS
Wrong IP → update A record to 72.60.97.82

Get Help

Contact the platform admin with:

App name and API server IP
Which database
Exact error message
Steps already tried