Datacenter-Control-Complete/TROUBLESHOOTING.md

Troubleshooting Guide

Authentication Issues

403 Forbidden from CloudFront

Symptoms:

• All login URL attempts return 403 Forbidden
• Error message mentions "CloudFront" or "distribution is not configured to allow the HTTP request method"

Possible Causes:

1. IP Address Restrictions: Your IP address may not be whitelisted in the Omada Cloud controller
2. Regional Restrictions: The endpoint may only be accessible from certain regions
3. CloudFront Configuration: CloudFront CDN may be blocking POST requests (only allows cacheable GET requests)
4. Endpoint Changes: The API endpoint structure may have changed

Solutions:

1. Verify Your IP is Whitelisted

   • Contact TP-Link/Omada support to whitelist your IP address
   • Check if your organization has IP restrictions configured

2. Check Regional Access

   • Verify that OMADA_CONTROLLER_BASE matches your region
   • EU: https://euw1-omada-controller.tplinkcloud.com
   • US: https://usw1-omada-controller.tplinkcloud.com
   • Asia: https://ap1-omada-controller.tplinkcloud.com

3. Use OAuth Instead

   • If password authentication is blocked, try using OAuth (Client ID/Secret)
   • Ensure TP_LINK_CLIENT_ID and TP_LINK_CLIENT_SECRET are configured
   • The system will automatically try OAuth first, then fall back to password

4. Contact TP-Link Support

   • Provide them with:
     • Your Omada ID
     • The exact error message
     • Your IP address
     • The endpoint you're trying to access

OAuth Authentication Not Working

Symptoms:

• OAuth Client Credentials flow fails
• System falls back to password authentication

Solutions:

1. Verify OAuth credentials are correct in .env
2. Check if TP-LINK Open API supports Client Credentials flow
3. You may need to implement Authorization Code flow instead
4. Contact TP-Link to verify OAuth endpoint and flow

Database Connection Issues

Symptoms:

• "Connection refused" or "Connection timeout"
• "Database does not exist"

Solutions:

1. Verify PostgreSQL is Running

   # Check if PostgreSQL is running
   sudo systemctl status postgresql
   # Or with Docker
   docker ps | grep postgres
   

2. Check DATABASE_URL

   DATABASE_URL=postgresql://user:password@host:port/database?schema=public
   

   • Verify username, password, host, and port are correct
   • Ensure the database exists

3. Test Connection

   # Using psql
   psql $DATABASE_URL
   
   # Or test with Prisma
   pnpm run prisma:studio
   

Missing Environment Variables

Symptoms:

• "Missing required environment variables" error on startup

Solutions:

1. Check .env file exists in project root

2. Verify all required variables are set:

   • OMADA_ID
   • OMADA_CONTROLLER_BASE
   • OMADA_NORTHBOUND_BASE
   • DATABASE_URL
   • JWT_SECRET
   • Either OAuth credentials OR username/password

3. Use setup script:

   pnpm run setup:env
   

API Endpoint Issues

404 Not Found

Symptoms:

• API calls return 404
• "Route not found" errors

Solutions:

1. Verify the endpoint URL is correct
2. Check if the Omada API version has changed
3. Ensure OMADA_NORTHBOUND_BASE is correct

Rate Limiting

Symptoms:

• 429 Too Many Requests errors
• API calls start failing after many requests

Solutions:

1. Implement request throttling
2. Add delays between requests
3. Cache responses when possible
4. Contact TP-Link about rate limits

Getting Help

1. Check Logs

   • Application logs: logs/combined.log
   • Error logs: logs/error.log
   • Set LOG_LEVEL=debug for detailed logging

2. Enable Debug Mode

   LOG_LEVEL=debug
   NODE_ENV=development
   

3. Test Authentication

   pnpm run test:auth
   

4. Contact Support

   • TP-Link Omada Support
   • Include error logs and configuration (redact sensitive info)