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**
   ```bash
   # Check if PostgreSQL is running
   sudo systemctl status postgresql
   # Or with Docker
   docker ps | grep postgres
   ```

2. **Check DATABASE_URL**
   ```env
   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**
   ```bash
   # 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:
   ```bash
   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**
   ```env
   LOG_LEVEL=debug
   NODE_ENV=development
   ```

3. **Test Authentication**
   ```bash
   pnpm run test:auth
   ```

4. **Contact Support**
   - TP-Link Omada Support
   - Include error logs and configuration (redact sensitive info)