Skip to main content

Troubleshooting Guide

This guide covers common issues you might encounter while developing with the Solverhood technology stack and provides solutions to resolve them.

🚨 Common Issues​

Development Environment Setup​

Port Already in Use​

Problem: Getting "port already in use" errors when starting services.

Solutions:

# Find process using the port
lsof -i :8080

# Kill the process
kill -9 <PID>

# Or use a different port
export PORT=8081

Docker Issues​

Problem: Docker containers won't start or are having connectivity issues.

Solutions:

# Stop all containers
docker-compose down

# Remove all containers and volumes
docker-compose down -v

# Rebuild containers
docker-compose up --build

# Check container logs
docker-compose logs <service-name>

Database Connection Issues​

Problem: Cannot connect to PostgreSQL or ClickHouse.

Solutions:

# Check if databases are running
docker-compose ps

# Restart database services
docker-compose restart postgres clickhouse

# Check database logs
docker-compose logs postgres
docker-compose logs clickhouse

# Test connection manually
psql -h localhost -U postgres -d solverhood
clickhouse-client --host localhost --port 9000

Go Development Issues​

Module Issues​

Problem: Go module dependencies not resolving correctly.

Solutions:

# Clean module cache
go clean -modcache

# Download dependencies
go mod download

# Tidy modules
go mod tidy

# Verify modules
go mod verify

Build Issues​

Problem: Go build failing with various errors.

Solutions:

# Check Go version
go version

# Clean build cache
go clean -cache

# Build with verbose output
go build -v ./...

# Check for race conditions
go build -race ./...

GQLGen Issues​

Problem: GraphQL code generation not working.

Solutions:

# Regenerate GraphQL code
go run github.com/99designs/gqlgen generate

# Clean and regenerate
rm -rf graph/generated
go run github.com/99designs/gqlgen generate

# Check schema syntax
go run github.com/99designs/gqlgen validate

Ent ORM Issues​

Problem: Ent schema generation or migration issues.

Solutions:

# Generate Ent code
go generate ./ent

# Run migrations
atlas migrate apply --url "postgres://postgres:password@localhost:5432/solverhood?sslmode=disable"

# Check migration status
atlas migrate status --url "postgres://postgres:password@localhost:5432/solverhood?sslmode=disable"

Frontend Development Issues​

Node.js/Package Issues​

Problem: pnpm install failing or packages not found.

Solutions:

# Clear cache
pnpm store prune

# Remove node_modules and reinstall
rm -rf node_modules pnpm-lock.yaml
pnpm install

# Update packages
pnpm update

# Check for outdated packages
pnpm outdated

TypeScript Issues​

Problem: TypeScript compilation errors or type issues.

Solutions:

# Check TypeScript version
npx tsc --version

# Type check with verbose output
npx tsc --noEmit --listFiles

# Reset TypeScript cache
rm -rf node_modules/.cache

React Development Issues​

Problem: React components not rendering or state issues.

Solutions:

# Clear React cache
rm -rf node_modules/.cache

# Restart development server
pnpm dev

# Check for React version conflicts
pnpm ls react react-dom

Build Issues​

Problem: Production build failing.

Solutions:

# Clean build directory
rm -rf dist build

# Build with verbose output
pnpm build --verbose

# Check bundle analyzer
pnpm build --analyze

Database Issues​

PostgreSQL Issues​

Problem: PostgreSQL connection or query issues.

Solutions:

-- Check connection
SELECT version();

-- Check active connections
SELECT * FROM pg_stat_activity;

-- Check table sizes
SELECT
    schemaname,
    tablename,
    pg_size_pretty(pg_total_relation_size(schemaname||'.'||tablename)) as size
FROM pg_tables
ORDER BY pg_total_relation_size(schemaname||'.'||tablename) DESC;

-- Check slow queries
SELECT query, mean_time, calls
FROM pg_stat_statements
ORDER BY mean_time DESC
LIMIT 10;

ClickHouse Issues​

Problem: ClickHouse query performance or connection issues.

Solutions:

-- Check system status
SELECT * FROM system.processes;

-- Check table sizes
SELECT
    database,
    table,
    formatReadableSize(total_bytes) as size
FROM system.tables
WHERE database = 'solverhood';

-- Check query performance
SELECT
    query,
    avg(query_duration_ms) as avg_duration,
    count() as query_count
FROM system.query_log
WHERE type = 'QueryFinish'
GROUP BY query
ORDER BY avg_duration DESC
LIMIT 10;

Redis Issues​

Problem: Redis connection or caching issues.

Solutions:

# Check Redis status
redis-cli ping

# Check Redis info
redis-cli info

# Monitor Redis commands
redis-cli monitor

# Check memory usage
redis-cli info memory

# Clear all keys (be careful!)
redis-cli flushall

NATS Issues​

Problem: NATS messaging or pub/sub issues.

Solutions:

# Check NATS server status
nats server report

# Monitor NATS traffic
nats sub ">" &

# Check NATS connections
nats server list

# Test NATS connectivity
nats pub test "Hello World"

🔧 Performance Issues​

Slow Database Queries​

Problem: Database queries taking too long.

Solutions:

-- Enable query logging
SET log_statement = 'all';
SET log_min_duration_statement = 1000;

-- Analyze query performance
EXPLAIN ANALYZE SELECT * FROM users WHERE email = 'test@example.com';

-- Check for missing indexes
SELECT schemaname, tablename, indexname, indexdef
FROM pg_indexes
WHERE schemaname = 'public';

Memory Issues​

Problem: High memory usage in applications.

Solutions:

# Check memory usage
top -p $(pgrep -f "your-app")

# Profile Go application
go tool pprof http://localhost:6060/debug/pprof/heap

# Check for memory leaks
go tool pprof http://localhost:6060/debug/pprof/allocs

Network Issues​

Problem: Network connectivity or latency issues.

Solutions:

# Test network connectivity
ping google.com

# Check DNS resolution
nslookup api.solverhood.com

# Test specific ports
telnet localhost 5432
telnet localhost 6379

# Check network interfaces
ifconfig
ip addr show

🐛 Debugging Techniques​

Go Debugging​

// Add debug logging
log.Printf("Debug: %+v", variable)

// Use pprof for profiling
import _ "net/http/pprof"

// Add to your main function
go func() {
    log.Println(http.ListenAndServe("localhost:6060", nil))
}()

Frontend Debugging​

// Add console logging
console.log('Debug:', variable);

// Use React DevTools
// Install React Developer Tools browser extension

// Use Redux DevTools (if using Redux)
// Install Redux DevTools browser extension

Database Debugging​

-- Enable query logging
SET log_statement = 'all';

-- Check for locks
SELECT * FROM pg_locks WHERE NOT granted;

-- Check for long-running queries
SELECT pid, now() - pg_stat_activity.query_start AS duration, query
FROM pg_stat_activity
WHERE (now() - pg_stat_activity.query_start) > interval '5 minutes';

📊 Monitoring and Logging​

Application Logs​

# View application logs
docker-compose logs -f app

# View specific service logs
docker-compose logs -f postgres

# Search logs for errors
docker-compose logs | grep ERROR

# Follow logs in real-time
docker-compose logs -f --tail=100

System Monitoring​

# Check system resources
htop
iotop
nethogs

# Check disk usage
df -h
du -sh *

# Check network connections
netstat -tulpn
ss -tulpn

🔒 Security Issues​

Authentication Issues​

Problem: JWT token validation or authentication problems.

Solutions:

# Check JWT token
echo "your.jwt.token" | cut -d. -f2 | base64 -d

# Verify token signature
# Use jwt.io or similar tools

# Check token expiration
# Decode token and check exp field

SSL/TLS Issues​

Problem: SSL certificate or HTTPS issues.

Solutions:

# Check SSL certificate
openssl s_client -connect api.solverhood.com:443

# Verify certificate chain
openssl verify -CAfile ca-bundle.crt certificate.crt

# Test HTTPS connection
curl -I https://api.solverhood.com

🚀 Deployment Issues​

Docker Deployment​

Problem: Docker containers failing in production.

Solutions:

# Check container health
docker ps -a

# View container logs
docker logs <container-id>

# Check resource usage
docker stats

# Restart containers
docker-compose restart

Kubernetes Issues​

Problem: Pods not starting or services not accessible.

Solutions:

# Check pod status
kubectl get pods

# View pod logs
kubectl logs <pod-name>

# Describe pod for details
kubectl describe pod <pod-name>

# Check service endpoints
kubectl get endpoints

📞 Getting Help​

When to Ask for Help​

  • You've tried the solutions above without success
  • The issue is affecting multiple team members
  • You're unsure about the root cause
  • The issue is blocking your work

How to Ask for Help​

  1. Describe the problem clearly: What are you trying to do?
  2. Include error messages: Copy the exact error text
  3. Provide context: What were you doing when the error occurred?
  4. Share your environment: OS, versions, configuration
  5. Show what you've tried: List the solutions you've attempted

Where to Get Help​

  • Team Chat: For quick questions
  • GitHub Issues: For bugs and feature requests
  • Code Reviews: For implementation questions
  • Documentation: Check if the issue is already documented

This troubleshooting guide should help you resolve most common issues. If you encounter a problem not covered here, please add it to this guide after finding a solution to help other team members!