Skip to main content

Troubleshooting

This guide covers common issues you may encounter when pairing OPBX with Cloudonix and how to resolve them.

Pairing Issues​

Invalid Domain UUID​

Symptoms:

  • Validation fails with "Invalid credentials"
  • Error message about Domain UUID

Solutions:

  1. Verify UUID format: Must be valid UUID (xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx)
  2. Check in Cloudonix Portal: Settings → Domain UUID
  3. Copy correctly: Ensure no extra spaces or characters

Invalid API Key​

Symptoms:

  • "Invalid credentials" error
  • Authentication failures

Solutions:

  1. Regenerate key: In Cloudonix Portal → API Keys → Create new
  2. Check key permissions: Ensure required permissions are enabled
  3. Verify key type: Must be Domain API Key, not Requests API Key

Network Connectivity Issues​

Symptoms:

  • "Network error" or "Connection timeout"
  • API calls fail intermittently

Solutions:

  1. Check internet connection: Test connectivity to api.cloudonix.io
  2. Firewall rules: Ensure outbound port 443 is open
  3. DNS resolution: Verify api.cloudonix.io resolves correctly
  4. Check Cloudonix status: Visit Cloudonix Status

Voice Application Creation Failed​

Symptoms:

  • Settings save but show warning about voice application
  • Webhooks not being configured

Solutions:

  1. Check API permissions: Ensure voiceapplication:write is enabled
  2. Check package limits: May have reached voice application limit
  3. Manual creation: Create voice application in Cloudonix Portal, then update settings
  4. Check webhook URL: Ensure it's publicly accessible

Extension Sync Issues​

Extension Not Syncing to Cloudonix​

Symptoms:

  • Extension shows "Local Only" status
  • Sync button doesn't work

Solutions:

  1. Run full sync: Click "Sync All" button
  2. Check credentials: Re-validate Cloudonix settings
  3. Check API limits: May have reached subscriber limit
  4. View error details: Check OPBX logs for specific errors

Subscriber Exists in Cloudonix But Not OPBX​

Symptoms:

  • Shows "Cloudonix Only" in sync comparison
  • Orphaned subscribers

Solutions:

  1. Import to OPBX: Use "Import from Cloudonix" option
  2. Delete in Cloudonix: If not needed, delete directly in portal
  3. Check sync: Run comparison to see full picture

Sync Timeout or Rate Limiting​

Symptoms:

  • Sync fails with timeout error
  • "Rate limit exceeded" message

Solutions:

  1. Wait and retry: Rate limits reset after some time
  2. Sync fewer at once: Sync extensions in batches
  3. Check Cloudonix package: May have API call limits

Webhook Issues​

Webhooks Not Received​

Symptoms:

  • Calls don't route correctly
  • No webhook logs in OPBX

Solutions:

  1. Check ngrok: Ensure running and URL is correct
  2. Verify webhook URLs: Check in Settings → Webhook URLs
  3. Check Cloudonix Portal: Verify webhook URLs in Voice Application
  4. Review ngrok inspector: Check if webhooks are arriving

Webhook Authentication Failures​

Symptoms:

  • "Unauthorized" in webhook logs
  • 401 errors

Solutions:

  1. Requests API Key: Ensure it's set in both OPBX and Cloudonix
  2. Check Bearer token: Verify format is correct
  3. Re-generate key: In OPBX Settings, generate new Requests API Key
  4. Update Cloudonix: Enter new key in Cloudonix Portal

Webhook Timeouts​

Symptoms:

  • Calls drop or don't complete
  • Timeout errors in logs

Solutions:

  1. Check OPBX logs: Identify what's causing delay
  2. Database performance: Ensure MySQL is responsive
  3. Queue backlog: Check Redis queue for stuck jobs
  4. Network latency: Test between Cloudonix and your server

Call Routing Issues​

Calls Not Routing to Extensions​

Symptoms:

  • Call arrives but nothing happens
  • Caller hears silence or error

Solutions:

  1. Check routing: Verify DID is mapped to extension/ring group
  2. Check webhook route: Ensure voice route webhook returns valid CXML
  3. Check extension status: Ensure extension is Active
  4. Review logs: Check OPBX logs for routing errors

Calls Go to Voicemail Immediately​

Symptoms:

  • Extension rings briefly then goes to voicemail

Solutions:

  1. Check timeout: Increase No Answer Timeout in Settings
  2. Check extension status: Extension must be Active
  3. Check SIP registration: If using SIP phone, ensure registered
  4. Check business hours: Ensure within business hours if configured

Ring Group Not Working​

Symptoms:

  • Ring group doesn't ring multiple extensions

Solutions:

  1. Check members: Ensure extensions are added to ring group
  2. Check strategy: Verify ring group strategy (simultaneous, round-robin)
  3. Check timeout: Increase ring group timeout

Diagnostic Steps​

Step 1: Check OPBX Logs​

# View Laravel logs
docker compose logs app --tail=100

# Filter for Cloudonix-related logs
docker compose logs app | grep -i cloudonix

Step 2: Check Cloudonix Portal​

  1. Voice Applications: Verify app exists and is default
  2. Subscribers: Verify extensions synced correctly
  3. API Keys: Verify permissions
  4. Webhook Logs: Check delivery status

Step 3: Test Connectivity​

# Test API connectivity
curl -I https://api.cloudonix.io

# Test webhook endpoint
curl -X POST https://your-webhook-url/api/voice/route \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

Step 4: Re-validate Credentials​

  1. Go to Settings
  2. Click "Validate & Save"
  3. Fix any errors shown

Step 5: Full Re-sync​

  1. Go to Extensions
  2. Click "Sync All"
  3. Monitor for errors

Getting Help​

If you've tried these solutions and still have issues:

Gather Information​

Before contacting support, collect:

  1. OPBX version
  2. Cloudonix package/tier
  3. Steps to reproduce
  4. Relevant logs
  5. Screenshots of errors

Support Channels​

Common Error Messages​

ErrorMeaningSolution
Invalid Domain UUIDUUID format wrong or doesn't existVerify in Cloudonix Portal
Invalid API KeyKey is wrong or revokedRegenerate in Portal
Network ErrorCan't reach CloudonixCheck connectivity
Rate LimitedToo many API callsWait and retry
Voice App Not FoundVoice application missingRe-save settings
Webhook TimeoutOPBX taking too longCheck performance
401 UnauthorizedAuthentication failedCheck API keys

Prevention Tips​

  1. Use HTTPS in production: Never use HTTP
  2. Monitor logs: Regularly check for errors
  3. Keep credentials secure: Don't share API keys
  4. Test after changes: Make test calls after configuration changes
  5. Keep packages updated: Both OPBX and Cloudonix

Related Documentation: