Connection Error

What this error means

Root causes

How to fix it

1. 1

   Verify microphone permissions in the browser or OS

   Confirm the user has granted microphone access to your web application. In Chrome, check the padlock icon in the address bar and ensure microphone access is set to 'Allow'. On mobile, check system settings under Privacy > Microphone. Twilio Client requires microphone access to establish audio media.

2. 2

   Enable TURN server usage in Twilio Client configuration

   Configure Twilio Client to use TURN servers, which relay media traffic to traverse strict NAT and firewalls. When initializing the Twilio Device, pass the ICE transport policy as 'relay' to force TURN usage in environments where direct UDP is blocked.

   import { Device } from '@twilio/voice-sdk';
   
   const device = new Device(token, {
     // Force TURN relay for restrictive networks
     iceServers: [
       {
         urls: 'turn:global.turn.twilio.com:3478',
         username: token, // Use a real TURN credential from Twilio Tokens API
         credential: turnCredential
       }
     ],
     // Log ICE connection events for debugging
     logLevel: 'DEBUG'
   });
   
   device.on('error', (error) => {
     console.error('Twilio Device error:', error.code, error.message);
   });

3. 3

   Check firewall rules for required UDP ports

   Twilio Client requires outbound UDP access to Twilio's STUN/TURN servers on the following ports: UDP 3478 (STUN/TURN), UDP 5349 (TURN over TLS), and UDP 10000-60000 (media). Work with your network team to allow these ports for Twilio's IP ranges. See https://help.twilio.com/articles/223180588 for the current Twilio IP list.

4. 4

   Implement 31005 error handling with user-facing guidance

   When a 31005 error fires, display a clear, actionable message to the user rather than a generic failure. Guide them to check their network, try a different network, or use a fallback PSTN number.

   device.on('error', (twilioError) => {
     if (twilioError.code === 31005) {
       showUserMessage({
         type: 'error',
         title: 'Audio connection failed',
         body: 'Your network may be blocking voice calls. ' +
               'Try switching to a different Wi-Fi network or mobile data, ' +
               'then retry the call.'
       });
       // Log for ops monitoring
       logger.error('twilio_31005', {
         userAgent: navigator.userAgent,
         networkType: navigator.connection?.type
       });
     }
   });

5. 5

   Test connectivity with Twilio's network diagnostics tool

   Use Twilio's Network Test Suite (https://networktest.twilio.com) to diagnose client-side connectivity issues. This tool tests STUN, TURN, and media connectivity from the user's browser and reports which paths are blocked. Share the diagnostic report with your network team to identify specific firewall rules that need adjustment.

6. 6

   Enable preflight connectivity check before call initiation

   Use Twilio's PreflightTest to check media connectivity before placing a real call. Run this check on application load and warn users proactively if their network cannot support media.

   import { runPreflight } from '@twilio/voice-sdk';
   
   async function checkMediaConnectivity(token) {
     const preflight = runPreflight(token);
     
     return new Promise((resolve, reject) => {
       preflight.on('completed', (report) => {
         console.log('Preflight report:', report);
         if (report.isTurnRequired) {
           console.warn('TURN required — user is behind restrictive NAT');
         }
         resolve(report);
       });
       
       preflight.on('failed', (error) => {
         console.error('Preflight failed:', error);
         reject(error);
       });
     });
   }

7. 7

   Monitor ICE connection state changes for early detection

   Subscribe to ICE connection state events on the Twilio Call object to detect media path failures as they happen, not just at final error. This gives you more diagnostic data for each failure.

8. 8

   Provide a PSTN fallback for media-blocked environments

   For enterprise customers behind strict firewalls, provide an alternative PSTN dial-in number so they can join calls via regular phone. This eliminates the dependency on WebRTC media traversal for users in highly restricted network environments.

Prevention

Prevent 31005 errors by implementing a pre-call network preflight check using Twilio's PreflightTest API before allowing users to start calls. Configure TURN servers properly and test your application from behind common enterprise firewall configurations. Implement clear user-facing error messages with actionable troubleshooting steps when connection failures occur. Monitor 31005 error rates in your application telemetry segmented by user location and device type to identify which user populations are most affected. For enterprise deployments, work with IT administrators proactively to whitelist Twilio's IP ranges and required UDP ports.