> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streampixel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Reconnection

> Automatic reconnection state machine for WebSocket drops, including disconnect codes, reasons, and parent window messages.

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

<Warning>
  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.
</Warning>

## 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`

<Info>
  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.
</Info>

## Listening for reconnection state

```javascript theme={"dark"}
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

| Status           | Description                                                                  |
| ---------------- | ---------------------------------------------------------------------------- |
| `"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:

| Reason                      | Description                              |
| --------------------------- | ---------------------------------------- |
| `"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):

```javascript theme={"dark"}
// The SDK posts this message automatically on disconnect
window.parent.postMessage({
  type: 'stream-state',
  value: 'disconnected',
  code: 4007
}, '*');
```

## Next steps

<CardGroup cols={2}>
  <Card title="Connection lifecycle" href="/resources/web-sdk/core-concepts/connection-lifecycle">
    Map the events fired during initial connection setup.
  </Card>

  <Card title="Queue system" href="/resources/web-sdk/features/queue-system">
    Display queue position updates when UE instances are busy.
  </Card>
</CardGroup>