2. Check Logs

# Database logs
docker compose logs postgres

# If running API/importer/evaluator in terminal, check that output

3. Verify Configuration

# Check .env exists and has required values
cat .env | grep POSTGRES

Required variables:

POSTGRES_HOST
POSTGRES_PORT
POSTGRES_USER
POSTGRES_PASSWORD
POSTGRES_DB

Common Issues

Database Connection Refused

Symptoms: Services fail with "connection refused" or "could not connect"

Diagnosis:

docker compose ps  # Is postgres running?
docker compose logs postgres  # Any errors?

Fixes:

Start database: task compose:up
Check POSTGRES_HOST in .env (should be postgres in DevContainer, localhost outside)

Port Already in Use

Symptoms: "address already in use" error on startup

Diagnosis:

lsof -i :8080  # or whatever port

Fixes:

kill -9 <PID>
# or change the port in .env

Migrations Not Applied

Symptoms: "relation does not exist" SQL errors

Diagnosis:

docker compose exec postgres psql -U $POSTGRES_USER -d $POSTGRES_DB -c "\dt"

Fixes:

task migrate:up

Empty Database / Missing Data

Symptoms: API returns empty results, evaluator finds nothing to process

Diagnosis:

docker compose exec postgres psql -U $POSTGRES_USER -d $POSTGRES_DB -c "SELECT COUNT(*) FROM weapons;"

Fixes:

task importer:start:use-cache

Stale or Corrupted Data

Symptoms: Unexpected behavior, data inconsistencies

Full reset:

task compose:down
docker compose down -v  # removes volumes
task compose:up
task migrate:up
task importer:start

Build Failures

Symptoms: task api:build or similar fails

Diagnosis:

go build ./...  # See actual error

Common fixes:

Missing dependencies: go mod tidy
Syntax errors: Check the error message for file/line

Database Inspection

Quick commands for checking database state:

# Connect to database
docker compose exec postgres psql -U $POSTGRES_USER -d $POSTGRES_DB

# Once connected:
\dt                          # List tables
SELECT COUNT(*) FROM weapons;
SELECT COUNT(*) FROM weapon_mods;
SELECT COUNT(*) FROM optimum_builds;
\q                           # Exit

troubleshoot-local-dev

Troubleshoot Local Dev Skill

Diagnostic Steps

1. Check Service Status