Troubleshoot Local Dev Skill

Use this skill when local services fail to start or behave unexpectedly.

Diagnostic Steps

1. Check Service Status

docker compose ps

If PostgreSQL isn’t running or is unhealthy, start it:

task compose:up

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