Skip to content

Troubleshooting Guide

Common issues and solutions for developers working with the Portugal Odyssey platform.

Quick Diagnostics

Check Service Status

# Development
make dev-logs

# Qualification
make qual-logs

# Check specific service
docker logs po-service-name-qual --tail=50

Check Network Connectivity

# Test service connectivity
docker exec po-service-name-qual ping postgres
docker exec po-service-name-qual ping redis
docker exec po-service-name-qual ping rabbitmq

Common Issues

Service Won't Start

Symptoms: - Container exits immediately - Service shows as "Restarting"

Solutions: 1. Check logs: docker logs po-service-name-qual 2. Verify environment variables: docker exec po-service-name-qual env 3. Check dependencies: Ensure databases/services are running 4. Verify configuration: Check .env files

Database Connection Errors

Symptoms: - ECONNREFUSED errors - database does not exist errors

Solutions: 1. Verify PostgreSQL is running: docker ps | grep postgres 2. Check database exists: docker exec po-postgres psql -U postgres -l 3. Verify connection string in .env file 4. Check network connectivity

Port Already in Use

Symptoms: - bind: address already in use - Service can't start

Solutions: 

# Find process using port
lsof -i :3000  # macOS/Linux
netstat -ano | findstr :3000  # Windows

# Kill process or change port in .env

RabbitMQ Connection Issues

Symptoms: - vhost not found errors - Connection refused

Solutions: 1. Check RabbitMQ is running: docker ps | grep rabbitmq 2. Verify virtual host exists: docker exec po-rabbitmq rabbitmqctl list_vhosts 3. Check connection URL format: amqp://user:pass@rabbitmq:5672/vhost 4. See RabbitMQ Setup

Environment Variables Not Loading

Symptoms: - Variables are undefined - Default values being used

Solutions: 1. Verify .env file exists: ls -la .env.dev 2. Check Docker Compose reads it: docker compose config 3. Verify variable names match exactly 4. Check for typos in variable names

Service-Specific Issues

Frontend Build Failures

Symptoms: - Build errors during npm run build - TypeScript errors

Solutions: 1. Clear node_modules: rm -rf node_modules && npm install 2. Clear build cache: rm -rf dist 3. Check TypeScript version compatibility 4. Review error messages for specific issues

Strapi CMS Issues

Symptoms: - Falls back to SQLite - Database connection errors

Solutions: 1. Verify PostgreSQL connection in services/strapi-cms/.env 2. Check pg package is installed: npm list pg 3. Verify database exists 4. Check network connectivity

Debugging Tips

Enable Debug Logging

# Set debug environment variable
export DEBUG=*
make dev

View Real-time Logs

# Follow logs
docker logs -f po-service-name-qual

# Filter logs
docker logs po-service-name-qual 2>&1 | grep ERROR

Inspect Container

# Enter container
docker exec -it po-service-name-qual sh

# Check environment
docker exec po-service-name-qual env

# Check network
docker exec po-service-name-qual ping postgres

Getting Help

  1. Check Logs - Always check service logs first
  2. Review Documentation - Check service-specific docs
  3. Search Issues - Look for similar issues in GitLab
  4. Ask Team - Contact team members for help

See Also