Troubleshooting Guide

Root Cause

Config file values in config.yaml override environment variables. Hardcoded password in config.yaml overrides DB_PASSWORD env var.

Solution

• 1Remove any password value from packages/gateway-core/configs/config.yaml
• 2Ensure DB_PASSWORD environment variable is set correctly in .env file
• 3Verify config.yaml has: # password: removed - use DB_PASSWORD environment variable
• 4Restart gateway service: docker-compose restart gateway

Diagnostic Commands

docker-compose exec gateway printenv | grep DB_PASSWORD

docker-compose exec postgres psql -U b2alabs -d b2alabs -c "SELECT 1"

Root Cause

Init scripts try to INSERT data before schema is created by migrations

Solution

• 1Disable init scripts in docker-compose.yml by removing or renaming them
• 2Let gateway migrations create schema first on startup
• 3After gateway starts successfully, run seed scripts manually if needed
• 4Proper order: 1) Start database 2) Run migrations 3) Seed data

Diagnostic Commands

docker-compose exec gateway ./migrate -database "postgres://..." -path ./migrations version

cd packages/gateway-core && make migrate-up

Root Cause

PostgreSQL takes 10-15 seconds to fully initialize after container starts

Solution

• 1Wait 15-20 seconds after starting postgres before starting gateway
• 2Use docker-compose wait or health checks
• 3Gateway will retry connection automatically
• 4CheckIcon PostgreSQL logs: docker-compose logs postgres

Diagnostic Commands

docker-compose exec postgres pg_isready -U b2alabs

docker-compose logs postgres --tail 50

Root Cause

Connection pool size too small for load, or connections not being released

Solution

• 1Increase PostgreSQL max_connections in config
• 2CheckIcon for long-running queries or hung connections
• 3Verify connection pooling settings in GORM
• 4Monitor connection metrics in Grafana

Diagnostic Commands

docker-compose exec postgres psql -U b2alabs -d b2alabs -c "SELECT count(*) FROM pg_stat_activity"

docker-compose exec postgres psql -U b2alabs -d b2alabs -c "SELECT pid, usename, application_name, state FROM pg_stat_activity"

Root Cause

Old containers from previous runs still exist

Solution

• 1Remove old containers: docker rm -f container_name
• 2Or use docker-compose down to stop and remove all
• 3Clean restart: docker-compose down -v && docker-compose up -d

Commands

docker ps -a

docker rm -f b2alabs-gateway

docker-compose down -v && docker-compose up -d

Root Cause

Missing dependencies, network issues, or incorrect Dockerfile

Solution

• 1CheckIcon Dockerfile for correct base image and dependencies
• 2Clear Docker build cache: docker system prune -a
• 3Verify network connectivity for package downloads
• 4For optional services (like ml-service), skip if not needed

Commands

docker-compose build --no-cache gateway

docker-compose build gateway 2>&1 | tee build.log

Root Cause

Another service is using the required port

Solution

• 1Find process using port: netstat -ano | findstr :8080 (Windows) or lsof -i :8080 (Linux/Mac)
• 2Stop the conflicting service
• 3Or change port in docker-compose.yml
• 4Common conflicts: Local PostgreSQL (5432), Redis (6379), dev servers (3000, 8080)

Commands

lsof -i :8080

netstat -ano | findstr :8080

kill -9 <PID>  # Linux/Mac
taskkill /PID <PID> /F  # Windows

Root Cause

JWT_SECRET changed between token creation and validation, or different secrets in different services

Solution

• 1Ensure JWT_SECRET is the same across all services
• 2Verify JWT_SECRET is at least 32 characters in production
• 3Regenerate API keys after changing JWT_SECRET
• 4CheckIcon config.go security validation (lines 327-356)

Commands

docker-compose exec gateway printenv | grep JWT_SECRET

docker-compose exec gateway sh -c 'echo -n "$JWT_SECRET" | wc -c'

Root Cause

User not created, email mismatch, or database not seeded

Solution

• 1Register user first: POST /api/v1/auth/register
• 2Verify user exists in database
• 3CheckIcon email format (must be lowercase in database)
• 4Ensure migrations ran successfully

Commands

docker-compose exec postgres psql -U b2alabs -d b2alabs -c "SELECT id, email, name FROM users"

curl -X POST http://localhost:8080/api/v1/auth/register -H "Content-Type: application/json" -d '{"email":"test@example.com","password":"Test123!","name":"Test User"}'

Root Cause

API key not created, expired, or incorrect header format

Solution

• 1Create API key via authenticated endpoint
• 2Use header: X-API-KeyIcon: your_key_here
• 3Verify API key is active and not revoked
• 4CheckIcon permissions on the API key

Commands

curl -X POST http://localhost:8080/api/v1/auth/api-keys -H "Authorization: Bearer YOUR_JWT" -H "Content-Type: application/json" -d '{"name":"My Key","permissions":["read","write"]}'

curl -X GET http://localhost:8080/health -H "X-API-KeyIcon: your_key_here"

Root Cause

Memory leak, insufficient resources, or large cache size

Solution

• 1Increase container memory limits in docker-compose.yml
• 2CheckIcon for memory leaks in custom code
• 3Reduce cache size (MEMORY_MAX_SIZE)
• 4Use Redis cache instead of in-memory (CACHE_TYPE=redis)
• 5Monitor with: docker stats

Diagnostic Commands

docker stats --no-stream b2alabs-gateway

docker inspect b2alabs-gateway | grep -i oom

Root Cause

CircleStackIcon queries not optimized, missing indexes, or network latency

Solution

• 1Enable query logging: LOG_LEVEL=DEBUG
• 2CheckIcon slow queries in PostgreSQL logs
• 3Ensure caching is enabled: CACHING_ENABLED=true
• 4Use CACHE_TYPE=redis for distributed caching
• 5Monitor metrics in Grafana dashboard

Diagnostic Commands

docker-compose exec postgres psql -U b2alabs -d b2alabs -c "ALTER DATABASE b2alabs SET log_min_duration_statement = 1000"

docker-compose logs postgres | grep "duration:"