Diagnosing Connection Errors with 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 https://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

First, if you are using LiveKit React Components, you can run connection checks as part of your error handling in 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.

Available Tests

• WebRTC connectivity (source | ConnectionCheck.checkWebRTC())

  • Verifies a WebRTC connection to the LiveKit servers can be made successfully

• Websocket connectivity (source | ConnectionCheck.checkWebsocket())

  • Verifies a Websocket connection to the LiveKit servers can be established successfully

• TURN (source | ConnectionCheck.checkTURN())

  • Verifies a connection to the LiveKit servers using TURN is successful

• Reconnect (source | ConnectionCheck.checkReconnect())

  • Verifies a connection can be resumed after interruption

• Publish Audio (source | ConnectionCheck.checkPublishAudio())

  • Verifies audio frames from the microphone device can be retrieved and published to the LiveKit servers

• Publish Video (source | ConnectionCheck.checkPublishVideo())

  • Verifies video frames from the camera device can be retrieved and published to the LiveKit servers

• Connection protocol (source | ConnectionCheck.checkConnectionProtocol())

  • Compares TCP with UDP connectivity

• Cloud Region (source | ConnectionCheck.checkCloudRegion())

  • Checks the connections quality of closest Cloud regions and determines which of the connections is the best quality

Best Practices

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

• WebSocket connectivity

• WebRTC connectivity

• 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-sdk';

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:

• Check their firewall settings

• Disable VPN temporarily to test connectivity

• Contact their IT department to allow LiveKit connections