Troubleshooting

General Diagnosis Steps

When an issue occurs, follow this sequence:

1. Check Docker container status: docker-compose ps
2. Check logs: docker-compose logs --tail=50 <service>
3. Check network: Test inter-service connectivity
4. Check resources: docker stats --no-stream

Database Issues

PostgreSQL Container Won't Start

Symptom: docker-compose ps shows postgres as Exit

Resolution:

# 1. Check logs
docker-compose logs postgres

# 2. Volume permission issue
docker-compose down
docker volume rm hereby-dhub_postgres_data
docker-compose up -d postgres

# 3. Port conflict
lsof -i :5432

DANGER

docker volume rm deletes all data. Always backup first.

Database Connection Failure

Symptom: ECONNREFUSED or connection timeout from API server

Resolution:

# 1. Check PostgreSQL status
docker exec hereby_postgres pg_isready -U hereby_admin

# 2. Verify .env connection settings
cat .env | grep DB_

# 3. Check Docker network
docker network ls
docker network inspect hereby-dhub_default

# 4. Restart containers
make db-restart

Migration Failure

# 1. Check migration status
pnpm --filter @hereby/database typeorm migration:show -d src/config/data-source.ts

# 2. Revert last migration
pnpm --filter @hereby/database typeorm migration:revert -d src/config/data-source.ts

# 3. Fix migration file and retry
make db-migrate

API Server Issues

API Server Won't Start

# 1. Check dependencies
pnpm install

# 2. Check build errors
pnpm --filter @hereby/api build

# 3. Verify environment variables
cat .env | grep -E "API_|JWT_|DB_"

# 4. Check database connectivity
docker exec hereby_postgres pg_isready -U hereby_admin

Slow API Responses

# 1. Check slow queries (in PostgreSQL shell)
SELECT pid, now() - query_start AS duration, query
FROM pg_stat_activity
WHERE state != 'idle'
  AND now() - query_start > interval '1 seconds';

# 2. Check Redis status
docker exec hereby_redis redis-cli info stats

# 3. Check resource usage
docker stats --no-stream

Redis Issues

Redis Connection Failure

docker-compose ps redis
docker exec hereby_redis redis-cli ping
docker-compose restart redis

Redis Memory Exceeded

docker exec hereby_redis redis-cli info memory
# Flush all cache (caution)
docker exec hereby_redis redis-cli FLUSHALL

Frontend Issues

App Won't Load

1. Verify API server is running
2. Check browser developer tools (F12) console for errors
3. Check Network tab for failed API requests
4. Verify CORS settings (CORS_ORIGIN in .env)

Authentication Errors (401/403)

1. Check JWT token expiration
2. Verify JWT_SECRET matches between API and .env
3. Clear browser localStorage and re-login

Build Issues

Build Failure

# 1. Clean build
pnpm clean
pnpm install
pnpm build

# 2. Build specific packages
pnpm --filter @hereby/core build
pnpm --filter @hereby/database build
pnpm --filter @hereby/api build

# 3. Auto-fix lint errors
pnpm lint:fix

TypeScript Type Errors

# Type check only
pnpm --filter @hereby/api type-check

# Build dependencies first
pnpm --filter @hereby/core build && pnpm --filter @hereby/database build

Emergency Contacts

Situation	Owner	Contact
DB Outage	DBA / IT Admin	—
API Server Outage	Development Team	—
Security Incident	Security Officer	—

INFO

Fill in emergency contacts per your organization's policy.