Skip to main content
The SDK includes automatic reconnection when the WebSocket connection to the signaling server drops unexpectedly. This page documents the reconnection flow, state values, and disconnect codes.

​
When reconnection triggers

Automatic reconnection activates only for WebSocket close codes 1005 and 1006 (abnormal closures — typically network issues). All other close codes indicate intentional disconnections and will show the disconnect overlay instead.

​
Reconnection flow

  1. WebSocket closes with code 1005 or 1006
  2. SDK emits reconnectStream state: "disconnected"
  3. SDK emits state: "reconnecting"
  4. After a 5-second delay, SDK emits state: "retrying" and reconnects to the signaling server
  5. On success: SDK emits state: "connected" and the playStream event fires
  6. On failure or if 60 seconds have elapsed since the first disconnect: SDK emits state: "failed" with code 4007
The 60-second reconnection window starts from the first disconnect. If the connection drops repeatedly within that window, each attempt still counts against the 60-second limit.

​
Listening for reconnection state

reconnectStream.on('state', (data) => {
  switch (data.status) {
    case 'disconnected':
      // Connection lost
      // data.code — WebSocket close code
      // data.reason — Close reason string
      break;

    case 'reconnecting':
      // Reconnection process started
      showMessage('Reconnecting...');
      break;

    case 'retrying':
      // Actively attempting to reconnect
      showMessage('Retrying connection...');
      break;

    case 'connected':
      // Successfully reconnected
      showMessage('Reconnected!');
      break;

    case 'failed':
      // Reconnection gave up
      // data.code = 4007 (reconnection timeout)
      showMessage('Unable to reconnect. Please refresh the page.');
      break;
  }
});

​
State values

StatusDescription
"disconnected"WebSocket closed. data.code and data.reason are available.
"reconnecting"Reconnection process initiated
"retrying"Reconnection attempt in progress (after 5-second delay)
"connected"Successfully reconnected and streaming again
"failed"Reconnection failed. data.code is 4007 when the 60-second window expires

​
Disconnect codes and reasons

When the connection closes intentionally, data.reason may contain one of these messages:
ReasonDescription
"Project Inactive"The project is disabled in the dashboard
"Worker Node Unavailable"No available compute nodes
"Application Not Found"The appId doesn’t match any project
"Application Error"The UE application crashed or errored
"Maximum Runtime Reached"The session exceeded its time limit
"No streamer connected"No UE instance is running
These disconnections do not trigger automatic reconnection.

​
Parent window communication

The SDK also sends disconnect events to the parent window (useful when the stream is embedded in an iframe): 
// The SDK posts this message automatically on disconnect
window.parent.postMessage({
  type: 'stream-state',
  value: 'disconnected',
  code: 4007
}, '*');

​
Next steps

Connection lifecycle

Map the events fired during initial connection setup.

Queue system

Display queue position updates when UE instances are busy.