Twilio error 31003 means the Voice SDK started the process of establishing a connection for a call but did not complete the connection within the allowed time window. This timeout can occur during the ICE (Interactive Connectivity Establishment) candidate gathering phase, during the DTLS handshake for media encryption, or during the SIP signaling registration step. Network firewalls and restrictive corporate proxies are the most frequent real-world cause, as they block the UDP and TCP ports that WebRTC requires.
What Causes This Error
Firewalls that block UDP traffic on ports 10000 to 60000 (the range WebRTC uses for media transport) prevent ICE candidates from being exchanged and cause the connection attempt to time out waiting for a viable media path to be established. Corporate networks that block STUN server traffic on UDP port 3478 prevent the ICE agent from discovering its own public IP address, causing ICE candidate gathering to fail and eventually time out with 31003. TURN server connectivity problems, where the Twilio NTS (Network Traversal Service) TURN servers are unreachable from the client's network, prevent relay candidates from being gathered, leaving no viable connectivity path when direct and server-reflexive candidates are also blocked. Slow or overloaded client devices where the JavaScript event loop is saturated (for example, a page running intensive animations or data processing while the SDK is initializing) can cause the ICE gathering process to exceed its timeout because the SDK's event processing is delayed by competing JavaScript work.
How to Fix It Step by Step
Open the browser's WebRTC internals diagnostic page (chrome://webrtc-internals in Chrome or about:webrtc in Firefox) during a failed call attempt and check the ICE candidate gathering section to see whether local, server-reflexive (STUN), and relay (TURN) candidates were gathered: zero relay candidates almost always means TURN server connectivity is blocked. Initialize the Twilio Device with an explicit iceServers configuration that includes Twilio's NTS TURN servers by fetching a fresh NTS token from the Twilio API and passing the servers to the Device constructor: new Device(token, { iceServers: ntsTokenResponse.ice_servers }). Test your network's WebRTC connectivity using a WebRTC network test tool run directly from the user's browser, which tests UDP, TCP, and TURN relay connectivity and reports which paths are blocked. For users on restrictive corporate networks, configure the Twilio Device to prefer TCP-based TURN by filtering the fetched NTS servers to those using TCP transport and placing them first in the iceServers array, as TCP port 443 is almost universally allowed through corporate firewalls.
How to Prevent It from Recurring
Before initializing the Voice SDK on a user's device, run a pre-call connectivity check using the Device.testPreflight() method introduced in recent Twilio Voice SDK versions, which probes ICE connectivity and reports back whether a successful call is likely to be established, allowing you to show a user-facing warning if connectivity is insufficient before they attempt a call. For known restrictive network environments, use the forceAggressiveIceNomination option and configure the SDK to use TCP TURN as the first-preference ICE candidate type, maximizing the chance of connectivity through firewall-restricted networks. Monitor your call connection success rate by tracking the ratio of Device incoming or outgoing call events versus successful Connection established events in your application analytics, and alert when the success rate drops below 95 percent. Document the network requirements for your Voice SDK application (UDP ports 10000 to 60000 open, TCP port 443 to Twilio NTS servers accessible) in your end-user support documentation so that users on corporate networks can request the necessary firewall exceptions from their IT teams.
When to Call a Specialist
If ICE candidates are being gathered but 31003 timeouts still occur, the issue may be in the DTLS handshake phase rather than ICE, which requires packet-level analysis of the WebRTC negotiation to identify whether the handshake is starting but not completing. A specialist can configure a browser-based packet capture during a failing call attempt and analyze the DTLS handshake sequence to identify whether the timeout is on the ICE side or the DTLS side, which points to different root causes and fixes. You should also escalate if 31003 timeouts are occurring on a subset of users at a specific office location or behind a specific enterprise network, as this pattern indicates a network infrastructure change (new firewall rules, new proxy deployment) that the local IT team needs to be engaged to resolve. Persistent WebRTC connectivity failures in enterprise environments are one of the most complex Voice SDK issues to diagnose and fix without specialist tooling.
Conclusion
Error 31003 is a connection timeout caused by network or ICE configuration issues that is resolved by enabling TURN relay connectivity and running pre-call connectivity checks for users on restricted networks. If this error is blocking your production system, contact our team and we will diagnose and fix it within the hour.
Ready to Transform Your Business Communications?
Get a free consultation with our VoIP experts and discover how we can help you save costs, improve efficiency, and scale your business.
Comments (0)
Join the discussion and share your thoughts (AI-moderated for quality)
Be the first to comment
No comments yet. Share your thoughts below.