Troubleshooting Guide

Authentication Issues

GitHub OAuth Problems

• Verify the OAuth code matches the 20-character hexadecimal format
• Check that the code hasn't expired (GitHub OAuth codes are short-lived)
• Ensure GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET are correctly set in .env

JWT Authentication Failures

UnauthorizedException: Unauthorized

• Check JWT_SECRET matches between instances
• Verify token expiration (default is 1 day)
• Ensure Authorization header format: Bearer <token>
• Check if endpoint is decorated with @Public() when needed

Database Connection Issues

Prisma Connection Errors

Error: P1001: Can't reach database server

• Verify DATABASE_URL format in .env:

  postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@localhost:5432/${POSTGRES_DB}
  

• Check if PostgreSQL container is running:

  docker-compose ps postgres
  

• Verify PostgreSQL credentials match .env variables

Redis Connection Issues

Error: Redis connection to localhost:6379 failed

• Check if Redis container is running
• Verify Redis port is exposed in docker-compose.yml
• Test Redis connection:

  docker exec redis redis-cli ping
  

VM Management Issues

VM Provisioning Failures

• Check VM provider configuration
• Verify memory, disk, and CPU allocations
• Ensure provider service is accessible
• Check network connectivity to VM

Docker Deployment Issues

Container Build Failures

Error: No such file or directory

• Verify Dockerfile paths
• Check context in docker-compose.yml
• Ensure all required files are present in build context

Container Startup Issues

Exit 137 (Out of memory)

• Check container resource limits
• Verify host system resources
• Review service dependencies in compose files

Network Issues

Caddy Configuration

Error: Reverse proxy endpoint unreachable

• Check Caddy configuration files
• Verify CADDY_ROOT_DIR path
• Ensure services are running on configured ports
• Check network_mode settings in docker-compose

Domain Binding Issues

Error: Domain verification failed

• Verify domain ownership
• Check DNS configuration
• Ensure challenge response is correct
• Verify Caddy has permissions to write SSL certificates

WebSocket Connection Issues

Connection Failures

Error: Invalid handshake

• Check WebSocket authentication token
• Verify CORS settings
• Ensure client is using correct connection URL
• Check if WebSocket server is running

Development Environment

Hot Reload Issues

Error: Cannot find module

• Clear node_modules and reinstall:

  rm -rf node_modules
  yarn install
  

• Check tsconfig.json paths
• Verify file watching is working

Build Problems

Error: Type error TS2307

• Run type checking:

  yarn tsc --noEmit
  

• Check for circular dependencies
• Verify module imports

Getting Help

Debug Mode

Enable debug logging by setting environment variables:

DEBUG=* yarn start:dev

Support Resources

1. Check error logs in:

   • api/logs/
   • Docker container logs
   • Caddy server logs

2. Common Commands

   # View API logs
   docker logs api_container
   
   # Check database status
   docker exec postgres pg_isready
   
   # View Caddy config
   caddy fmt --overwrite