Diagnosing Connection Errors with the Connection Test Utility

If users are experiencing connectivity problems with LiveKit Cloud (e.g., seeing errors such as could not establish pc connection), you can use the Connection Test utility to help diagnose and troubleshoot the issue. This utility is available as a standalone tool on the livekit.io website at livekit.io/connection-test, or the tests can be run from a frontend using the underlying test code in the client-sdk-js SDK.

Running Connection Checks

You can choose how and when to run the connection checks. Here are a few options:

On ConnectionError

If you are using LiveKit React Components, you can run connection checks as part of your error handling in your LiveKitRoom implementation:

<LiveKitRoom
  video={true}
  audio={true}
  token={token}
  serverUrl={serverUrl}
  onError={(e: Error) => {
    if (e instanceof ConnectionError) {
      // run connection checks here
    }
  }}
>
  ...
</LiveKitRoom>

On App Start

Some customers run these tests proactively at the beginning of a session to identify potential issues before they impact the user experience.

Available Tests

The Connection Test utility provides the following checks:

Best Practices

To properly diagnose connection issues, you should run three essential checks at a minimum:

1. WebSocket connectivity
2. WebRTC connectivity
3. TURN server connectivity

Important: Create a separate LiveKit project for running these checks to avoid cluttering your production environment. Contact support to have this test project connected to your main account for billing purposes.

Implementation Example

import { ConnectionCheck } from 'livekit-client';

const checker = new ConnectionCheck({
  url: 'your-project-url',
  token: 'your-token'
});

// Run individual checks
const websocketResult = await checker.checkWebsocket();
const webrtcResult = await checker.checkWebRTC();
const turnResult = await checker.checkTURN();

// Check results
if (websocketResult.status === 'FAILED' && 
    webrtcResult.status === 'FAILED' && 
    turnResult.status === 'FAILED') {
  // Very likely a firewall/VPN issue
}

Interpreting Results

If all connection checks fail, this strongly indicates that the user's network (likely firewall or VPN) is blocking the necessary connections. In such cases, the user should:

1. Check their firewall settings – Ensure that the necessary ports and protocols are not being blocked
2. Disable VPN temporarily – Test connectivity without the VPN to isolate the issue
3. Contact their IT department – Request that LiveKit connections be allowed through the corporate firewall

Related Resources

• LiveKit Connection Tester – Run connection tests directly in your browser
• Firewall Tips for LiveKit Connectivity – Understand how media connectivity works and configure TURN
• Configuring Firewalls - LiveKit Docs – Official documentation on firewall configuration
• client-sdk-js on GitHub – Source code for the Connection Test utility