Troubleshoot Local Dev Skill
Use this skill when local services fail to start or behave unexpectedly.
Diagnostic Steps
- Check Service Status
docker compose ps
If PostgreSQL isn't running or is unhealthy, start it:
task compose:up
- Check Logs
Database logs
docker compose logs postgres
If running API/importer/evaluator in terminal, check that output
- 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