> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Troubleshooting Routes
> Diagnose and fix common route issues. Solutions for 404, 502, 504 errors, authentication failures, and connection problems.
# Troubleshooting Routes
Common issues with routes and how to fix them. Follow this guide to diagnose and resolve route problems quickly.
## Quick Diagnostics Checklist
Before diving into specific errors:
```text theme={"dark"}
✓ Route is enabled (check Routes page)
✓ Using correct tenant subdomain
✓ x-knoxcall-route header matches route name exactly
✓ API key is valid (if using API key auth)
✓ Client IP is whitelisted (if using IP auth)
✓ Backend is reachable from internet
✓ Check API logs for detailed error messages
```
## Common HTTP Status Codes
### 404 Not Found
**Meaning:** Route not found or doesn't exist
#### Possible Causes
**1. Route name mismatch**
```bash theme={"dark"}
# Wrong:
-H "x-knoxcall-route: My-Route"
# Correct:
-H "x-knoxcall-route: my-route"
```
Route names are **case-sensitive**.
**2. Route is disabled**
Check Routes page - route might be toggled OFF.
**Fix:**
1. Go to Routes → Find your route
2. Toggle **Enabled** to ON
3. Save
**3. Wrong subdomain**
```bash theme={"dark"}
# Wrong:
https://wrong-subdomain.knoxcall.com
# Correct:
https://a1b2c3d4.yourcompany.knoxcall.com
```
Check your correct subdomain in dashboard.
**4. Route deleted**
If route was recently deleted, recreate it.
#### Debug Steps
```bash theme={"dark"}
# 1. List all routes
curl https://api.knoxcall.com/v1/routes \
-H "Authorization: Bearer YOUR_API_KEY"
# 2. Verify route exists and is enabled
# 3. Check route name matches exactly
```
### 401 Unauthorized
**Meaning:** Authentication failed
#### Possible Causes
**1. Invalid API key**
```bash theme={"dark"}
# Check your API key
-H "x-knoxcall-key: tk_abc123_xyz789..."
```
**Fixes:**
* Copy key again from dashboard
* Ensure no extra spaces or line breaks
* Verify key hasn't been deleted
* Check key hasn't expired
**2. Missing API key**
If route requires API key but none provided:
```bash theme={"dark"}
# Add API key header
-H "x-knoxcall-key: YOUR_API_KEY"
```
**3. Using wrong authentication method**
Route configured for IP auth but API key provided (or vice versa).
**Fix:**
1. Check route settings
2. Match authentication method
3. Either provide API key OR ensure IP is whitelisted
#### Debug Steps
```bash theme={"dark"}
# 1. Verify API key format (should be 72 chars starting with tk_)
echo "YOUR_API_KEY" | wc -c
# 2. Test API key validity
curl https://api.knoxcall.com/v1/account \
-H "x-knoxcall-key: YOUR_API_KEY"
# 3. Check route authentication requirements
```
### 403 Forbidden
**Meaning:** IP not authorized or permission denied
#### Possible Causes
**1. IP not whitelisted**
Your IP address isn't in the client list.
**Fix:**
1. Navigate to **Clients** → **Add Client**
2. Add your IP address
3. Go to route → **Clients** tab
4. Assign client to appropriate environment
**Quick test:** Disable IP requirement temporarily:
1. Edit route
2. Toggle **Requires Clients** to OFF
3. Test request
4. Re-enable after testing
**2. Client not assigned to route**
Client exists but isn't assigned to this route/environment.
**Fix:**
1. Go to route → **Clients** tab
2. Add your client to the environment
3. Save
**3. Rate limit exceeded**
You've hit the rate limit.
**Response:**
```http theme={"dark"}
HTTP/1.1 429 Too Many Requests
X-RateLimit-Remaining: 0
Retry-After: 3600
```
**Fix:**
* Wait for rate limit to reset
* Request limit increase
* Optimize request frequency
#### Debug Steps
```bash theme={"dark"}
# 1. Check your public IP
curl https://api.ipify.org
# 2. Verify IP is in client list
# Go to Clients page → Search for your IP
# 3. Check client assignment
# Route → Clients tab → Verify client is listed
```
### 500 Internal Server Error
**Meaning:** KnoxCall encountered an error processing your request
#### Possible Causes
**1. Secret not found**
Route tries to inject secret that doesn't exist:
```json theme={"dark"}
{
"Authorization": "Bearer {{secret:missing_key}}"
}
```
**Fix:**
1. Navigate to **Secrets**
2. Create the missing secret
3. Update route configuration
**2. Invalid secret format**
Secret exists but has invalid format for use case.
**Fix:**
1. Check secret value format
2. Update if needed
3. Test route again
**3. Configuration error**
Invalid JSON in header/body injection.
**Fix:**
1. Edit route
2. Check JSON syntax in Header/Body Injection
3. Use online JSON validator
4. Save with valid JSON
#### Debug Steps
```bash theme={"dark"}
# 1. Check API logs
# Go to Logs → API Logs → Find your request
# Look for error details
# 2. Verify secrets exist
# Go to Secrets → Check all referenced secrets
# 3. Validate configuration JSON
# Copy Header/Body Injection JSON
# Validate at jsonlint.com
```
### 502 Bad Gateway
**Meaning:** Backend server is unreachable or returned invalid response
#### Possible Causes
**1. Backend is down**
Your backend server isn't running.
**Test:**
```bash theme={"dark"}
# Try reaching backend directly
curl https://your-backend.com/health
```
**Fix:**
* Start your backend server
* Verify backend is running
* Check backend logs
**2. Wrong backend URL**
Target URL in route settings is incorrect.
**Fix:**
1. Edit route
2. Check **Target Base URL**
3. Verify URL is correct
4. Include protocol: `https://`
5. Test URL directly: `curl https://your-backend.com`
**3. Backend not accessible from internet**
Backend is running but not reachable from KnoxCall.
**Common scenarios:**
* Backend running on `localhost`
* Backend behind firewall
* Backend only accessible via VPN
* Private IP address used
**Fix:**
* Deploy backend with public IP
* Open firewall rules for KnoxCall IPs
* Use VPN egress feature (Enterprise)
**4. SSL/TLS issues**
Backend has invalid SSL certificate.
**Errors:**
* Certificate expired
* Self-signed certificate
* Certificate domain mismatch
**Fix:**
* Renew SSL certificate
* Use valid CA-signed certificate
* For testing: Disable SSL verification in route settings (not recommended for production)
**5. Backend returning non-HTTP response**
Backend is running but returning invalid HTTP.
**Fix:**
* Check backend logs
* Ensure backend returns proper HTTP response
* Verify headers are correctly formatted
#### Debug Steps
```bash theme={"dark"}
# 1. Test backend directly
curl -v https://your-backend.com/endpoint
# 2. Check SSL certificate
openssl s_client -connect your-backend.com:443 -servername your-backend.com
# 3. Verify DNS resolution
nslookup your-backend.com
dig your-backend.com
# 4. Test from KnoxCall's perspective
# Use route testing tool in dashboard
```
### 504 Gateway Timeout
**Meaning:** Backend took too long to respond
#### Possible Causes
**1. Backend is slow**
Backend processing time exceeds timeout.
**Default timeout:** 30 seconds
**Fix:**
1. Edit route
2. Increase **Timeout** setting
3. Recommended max: 120 seconds
**Long-term fix:**
* Optimize backend performance
* Add caching
* Use async processing for long operations
**2. Backend is overloaded**
Too many requests overwhelming backend.
**Symptoms:**
* Slow response times
* High CPU/memory usage
* Database connection pool exhausted
**Fix:**
* Scale backend (add more instances)
* Optimize database queries
* Add caching layer
* Enable rate limiting
**3. Database timeout**
Backend waiting for slow database query.
**Fix:**
* Optimize SQL queries
* Add database indexes
* Increase database resources
* Implement query timeout
**4. Network latency**
High network latency between KnoxCall and backend.
**Fix:**
* Use closer region (Multi-region feature)
* Optimize network path
* Consider CDN for static content
#### Debug Steps
```bash theme={"dark"}
# 1. Measure backend response time
time curl https://your-backend.com/endpoint
# 2. Check backend metrics
# - CPU usage
# - Memory usage
# - Active connections
# - Database query time
# 3. Enable detailed logging on backend
# Log each processing step with timestamps
# 4. Increase timeout temporarily for testing
# Route settings → Timeout: 60s
```
## Authentication Issues
### "Invalid signature" errors
**Using request signing?**
**Causes:**
* Wrong signing secret
* Message format mismatch
* Timestamp too old/new
* Clock skew between client and server
**Fix:**
```javascript theme={"dark"}
// 1. Verify message format
const message = `${timestamp}.${method}.${path}.${JSON.stringify(body)}`;
// 2. Check timestamp is current
const now = Math.floor(Date.now() / 1000);
console.log('Current timestamp:', now);
// 3. Verify secret is correct
console.log('Using secret:', secret.substring(0, 10) + '...');
// 4. Log computed signature
console.log('Computed signature:', signature);
```
### OAuth2 token expired
**Error:** `401 Unauthorized` from backend
**Causes:**
* Access token expired
* Refresh token revoked
* OAuth2 secret needs reauthorization
**Fix:**
1. Go to **Secrets** → Select OAuth2 secret
2. Check token status
3. If expired, click **Reauthorize**
4. Complete OAuth2 flow again
## Connection Issues
### "Connection refused"
**Causes:**
* Backend not running
* Wrong port number
* Firewall blocking connections
**Fix:**
```bash theme={"dark"}
# 1. Check if backend is listening
netstat -an | grep YOUR_PORT
# 2. Test local connection
curl http://localhost:YOUR_PORT/health
# 3. Test from external IP
curl http://YOUR_PUBLIC_IP:YOUR_PORT/health
# 4. Check firewall rules
iptables -L -n
```
### "DNS resolution failed"
**Causes:**
* Domain doesn't exist
* DNS not configured
* DNS propagation not complete
**Fix:**
```bash theme={"dark"}
# 1. Verify domain exists
nslookup your-backend.com
# 2. Check DNS records
dig your-backend.com
# 3. Wait for DNS propagation (24-48 hours for new domains)
# 4. Use IP address temporarily
# Route → Target URL: https://203.0.113.50
```
### "SSL handshake failed"
**Causes:**
* Expired certificate
* Self-signed certificate
* Certificate hostname mismatch
**Fix:**
```bash theme={"dark"}
# 1. Test SSL
openssl s_client -connect your-backend.com:443
# 2. Check certificate expiration
echo | openssl s_client -connect your-backend.com:443 2>/dev/null | openssl x509 -noout -dates
# 3. Verify certificate matches domain
echo | openssl s_client -connect your-backend.com:443 2>/dev/null | openssl x509 -noout -subject
```
## Performance Issues
### High latency
**Symptoms:**
* Requests taking longer than expected
* Inconsistent response times
**Diagnose:**
```text theme={"dark"}
Total latency: 2,500ms
├─ KnoxCall processing: 50ms
├─ Network to backend: 150ms
├─ Backend processing: 2,200ms ← Problem here!
└─ Network back: 100ms
```
**Check in logs:**
* `knoxcall_time`: Time spent in KnoxCall
* `backend_time`: Time backend took to respond
* `total_time`: Total request time
**Fix:**
* If `backend_time` is high: Optimize backend
* If `network_time` is high: Use closer region
* If `knoxcall_time` is high: Contact support
### Intermittent failures
**Symptoms:**
* Some requests succeed, others fail
* No consistent pattern
**Possible causes:**
* Backend load balancer issues
* Database connection pool exhausted
* Memory leaks in backend
* Network instability
**Debug:**
```text theme={"dark"}
1. Check failure rate over time
2. Identify patterns (time of day, specific endpoints)
3. Review backend logs during failures
4. Monitor backend resource usage
```
## Testing & Debugging Tools
### Use API Logs
**Best debugging tool:**
1. Go to **Logs** → **API Logs**
2. Find your request
3. Expand to see:
* Full request headers/body
* Full response headers/body
* Error messages
* Latency breakdown
### Test in Dashboard
Use built-in testing tool:
1. Go to Routes → Select route
2. Click **Test Route**
3. Configure request
4. See detailed response
### Use verbose curl
```bash theme={"dark"}
curl -v https://a1b2c3d4.acme.knoxcall.com/api/test \
-H "x-knoxcall-route: my-route" \
-H "x-knoxcall-key: YOUR_KEY"
```
The `-v` flag shows:
* DNS resolution
* Connection establishment
* SSL handshake
* Request headers sent
* Response headers received
### Check Health Endpoint
Test backend directly:
```bash theme={"dark"}
# If your backend has a health endpoint
curl https://your-backend.com/health
# Expected:
HTTP/1.1 200 OK
{"status": "healthy"}
```
## Getting Help
If you're still stuck:
### 1. Gather Information
Before contacting support:
```text theme={"dark"}
- Route name
- Tenant subdomain
- Error message
- Request timestamp
- Expected behavior
- Actual behavior
- Steps to reproduce
```
### 2. Check API Logs
Find the failing request:
1. Go to Logs → API Logs
2. Copy Request ID
3. Include in support ticket
### 3. Export Configuration
Export route configuration:
1. Go to Routes → Select route
2. Click **Export**
3. Attach to support ticket
### 4. Contact Support
* **Email**: [support@knoxcall.com](mailto:support@knoxcall.com)
* **Chat**: Click support icon in dashboard
* **Phone**: Available for Enterprise customers
## Prevention Tips
### 1. Enable Health Checks
Monitor route health:
1. Edit route
2. Enable **Health Checks**
3. Set check interval: 60s
4. Set alert threshold
### 2. Set Up Alerts
Get notified of issues:
```text theme={"dark"}
Alert: Route Error Rate > 5%
Channels: Email, Slack
```
### 3. Use Staging Environment
Test changes before production:
```text theme={"dark"}
1. Create staging environment
2. Test route changes in staging
3. Verify everything works
4. Deploy to production
```
### 4. Monitor Regularly
Check dashboard weekly:
* Success rates
* Latency trends
* Error patterns
* Usage statistics
### 5. Keep Backend Logs
Maintain backend logs for debugging:
* HTTP request/response
* Processing time
* Error messages
* Stack traces
## Next Steps
View detailed request logs
Set up error alerts
Learn route testing
Get help from support
***
* **Level**: beginner to advanced
* **Time**: Reference guide
`troubleshooting`, `debugging`, `errors`, `fixes`, `support`