Twilio error 31005 means the Voice SDK attempted to establish a call connection but the attempt failed before a media session could be set up. Unlike 31003 (which is a timeout waiting for connection), 31005 is an active connection failure where the SDK received an error response or detected an irrecoverable state during the WebRTC offer/answer exchange or the signaling handshake. This error surfaces in the Device.on('error') handler and in the Call.on('error') handler depending on where in the call lifecycle the failure occurs.
What Causes This Error
SDP (Session Description Protocol) offer/answer negotiation failures are a primary cause, which happen when the browser's WebRTC implementation generates an SDP offer that Twilio's media servers cannot process, often due to a codec mismatch or a mandatory attribute that the remote end does not support. Signaling WebSocket disconnection during the ICE negotiation phase, caused by a brief network interruption or a proxy that terminates idle WebSocket connections, prevents the SDP answer from being delivered to the SDK, causing the connection attempt to fail. Browser-level errors during the RTCPeerConnection setup, such as a call to setLocalDescription or setRemoteDescription failing with a browser error, will cause the SDK to emit a 31005 error because the peer connection cannot be established without a valid local and remote SDP. Permission changes that revoke microphone access between the time the Device was initialized and the time the call was accepted, such as a browser security prompt that the user dismissed incorrectly, can also cause a 31005 if the SDK cannot acquire the media stream needed for the call.
How to Fix It Step by Step
Enable debug-level SDK logging and reproduce the error, then search the browser console output for any log entries containing 'setLocalDescription', 'setRemoteDescription', 'createOffer', or 'createAnswer' that show a JavaScript error or a rejected promise, which pinpoints the exact SDP negotiation step that failed. Check the browser console for any getUserMedia errors that occur when the call is accepted, which would indicate a media acquisition failure rather than a signaling failure, and handle them separately from the 31005 error handler. Verify that your application's Content Security Policy (CSP) headers do not block WebSocket connections to Twilio's signaling endpoints (wss://chunderw-vpc-gll.twilio.com) or TURN server connections, as a CSP violation silently blocks these connections and causes 31005. For applications that reuse a single Device instance across multiple calls, test whether creating a fresh Device instance for each call resolves the 31005, as some state corruption issues in the Device lifecycle only manifest on the second or subsequent call.
How to Prevent It from Recurring
Implement a reconnection strategy in your application that listens to the Call.on('error') event for code 31005 and automatically attempts a fresh call after a 2-second delay, displaying a user-friendly message explaining that the connection failed and a retry is in progress. Add WebRTC browser support detection before initializing the Device, using the Device.isSupported() static method, and show a browser compatibility warning to users on browsers that do not fully support the required WebRTC APIs, preventing 31005 errors caused by partial WebRTC implementations. Monitor your browser version distribution in your analytics data and correlate it with 31005 error rates to identify whether a specific browser version is causing a higher failure rate, allowing you to add version-specific workarounds or user upgrade prompts. Keep the Voice SDK updated to receive fixes for browser-specific WebRTC compatibility issues, which Twilio's SDK team patches as browsers ship WebRTC updates that change negotiation behavior.
When to Call a Specialist
If 31005 errors are consistently occurring during SDP negotiation and your debug logs show a specific browser error in the setRemoteDescription call, the issue may be a codec or SDP attribute that has changed in a recent browser update, and a specialist can identify whether a specific SDK configuration change or a browser-targeted workaround can resolve the incompatibility. A specialist is also useful when 31005 errors are intermittent and correlate with specific user network conditions (such as users on mobile data or VPNs) but not on stable broadband, as intermittent signaling WebSocket drops on these networks require specific reconnection handling that may not be covered by the default SDK behavior. You should escalate if 31005 errors started appearing after a recent deployment of your application, as a new CSP policy, a new proxy configuration, or a changed Device initialization parameter in the deployment may be the direct cause.
Conclusion
Error 31005 is a WebRTC negotiation failure that is debugged through browser console SDP logs and fixed by addressing codec issues, CSP policies, or media acquisition problems in the call setup sequence. 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.