151 lines
3.9 KiB
Markdown
151 lines
3.9 KiB
Markdown
# 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)
|
|
|