Debugging Guide

This skill helps you diagnose and fix common issues in the Shorted project.

Quick Diagnostics

bash

# Check if services are running
make dev-db && docker ps

# Check ports in use
lsof -i :3020  # Frontend
lsof -i :9091  # Backend
lsof -i :5438  # Database

# Kill stale processes
make clean-ports

# Full restart
make dev-stop && make dev

Common Issues

Backend Not Starting

Symptom: make dev-backend fails or hangs

Steps:

•
Check for port conflicts:
bash
```
lsof -i :9091
```
•
Kill stale processes:
bash
```
make clean-ports
```
•
Check database is running:
bash
```
docker ps | grep shorted_db
```

•

Test database connection:

bash

psql postgresql://admin:password@localhost:5438/shorts -c "SELECT 1"

•

Check for Go compilation errors:

bash

cd services && go build ./shorts/cmd/server/...

•

Check environment variables:

bash

echo $DATABASE_URL
# Should be: postgresql://admin:password@localhost:5438/shorts

Frontend Not Starting

Symptom: make dev-frontend fails

Steps:

•
Clear Next.js cache:
bash
```
make clean-cache
```

•

Reinstall dependencies:

bash

cd web && rm -rf node_modules && npm install

•
Check for TypeScript errors:
bash
```
cd web && npx tsc --noEmit
```
•
Check port availability:
bash
```
lsof -i :3020
```

Database Connection Issues

Symptom: "connection refused" or timeout errors

Steps:

•
Start the database:
bash
```
make dev-db
```
•
Check container status:
bash
```
docker ps
docker logs shorted_db
```

•

Wait for database to be ready:

bash

until docker exec shorted_db pg_isready -U admin -d shorts; do
  sleep 2
done

•

Test connection:

bash

psql postgresql://admin:password@localhost:5438/shorts -c "\dt"

•

If container won't start, reset:

bash

cd analysis/sql && docker compose down -v
cd analysis/sql && docker compose up -d postgres

API Returning 500 Errors

Symptom: Backend returns internal server errors

Steps:

•

Check backend logs (run in foreground):

bash

cd services && DATABASE_URL=postgresql://admin:password@localhost:5438/shorts \
  go run shorts/cmd/server/main.go

•

Test specific endpoint:

bash

curl -v -X POST http://localhost:9091/v1/topShorts \
  -H "Content-Type: application/json" \
  -d '{"period": "1m", "limit": 10}'

•

Check database has data:

bash

psql postgresql://admin:password@localhost:5438/shorts \
  -c "SELECT COUNT(*) FROM shorts"

•

Verify database schema:

bash

cd services && make migrate-version
cd services && make migrate-up

Data Not Showing on Frontend

Symptom: UI shows empty state or loading forever

Steps:

•
Check backend is responding:
bash
```
curl http://localhost:9091/health
```

•

Test API directly:

bash

curl -X POST http://localhost:9091/v1/topShorts \
  -H "Content-Type: application/json" \
  -d '{"period": "1m", "limit": 10}' | jq

•
Check browser console for errors (open DevTools)
•
Check network tab for failed requests

•

Verify environment variables in .env.local:

bash

cat web/.env.local
# Should have NEXT_PUBLIC_API_URL or similar

Integration Tests Failing

Symptom: make test-integration-local fails

Steps:

•
Ensure Docker is running:
bash
```
docker info
```
•
Clean up old containers:
bash
```
docker system prune -f
```

•

Run with verbose output:

bash

cd services && go test -v ./test/integration/... -timeout=20m

•
Check testcontainer logs in test output

Slow Database Queries

Symptom: API responses take >1 second

Steps:

•
Diagnose slow queries:
bash
```
make db-diagnose
```
•
Apply performance indexes:
bash
```
make db-optimize
```

•

Update statistics:

bash

psql postgresql://admin:password@localhost:5438/shorts \
  -c "ANALYZE shorts; ANALYZE \"company-metadata\"; ANALYZE stock_prices;"

•

Check query plan:

sql

EXPLAIN ANALYZE
SELECT * FROM shorts 
WHERE "PRODUCT_CODE" = 'BHP' 
ORDER BY "DATE" DESC 
LIMIT 100;

Build/Lint Errors

Symptom: make test fails on linting

Steps:

•
Run linting separately:
bash
```
make lint-frontend
make lint-backend
```
•
Auto-fix TypeScript issues:
bash
```
cd web && npm run lint -- --fix
```
•
Auto-fix Go issues:
bash
```
cd services && make lint-fix
```
•
Format code:
bash
```
make format
```

Debug Mode

Backend Verbose Logging

bash

cd services && LOG_LEVEL=debug \
  DATABASE_URL=postgresql://admin:password@localhost:5438/shorts \
  go run shorts/cmd/server/main.go

Frontend Debug

Add to web/.env.local:

code

DEBUG=*

PostgreSQL Query Logging

sql

-- Enable query logging (temporary)
SET log_statement = 'all';
SET log_duration = on;

Health Checks

bash

# Backend health
curl http://localhost:9091/health

# Database health
docker exec shorted_db pg_isready -U admin -d shorts

# Full system check
make health-check

Log Locations

Service	How to View
Backend	Terminal output (foreground) or `docker logs`
Frontend	Terminal output + browser DevTools
Database	`docker logs shorted_db`
Cloud Run	`make daily-sync-logs`

Useful Commands

bash

# See all running containers
docker ps

# See all processes on common ports
lsof -i :3020,9091,5438,8090

# Database shell
psql postgresql://admin:password@localhost:5438/shorts

# Watch backend logs
cd services && make run.shorts 2>&1 | tee backend.log

# Generate fresh mocks (if tests fail on mock errors)
cd services && go generate ./...