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