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

# Reliability

> What the Streampixel Web SDK does when things go wrong, with the exact timings: signalling drops, a dead video connection, no video, a blocked network, relay fallback, an app that stops, and what your page sees for each.

Expert For developers who want the exact mechanism behind every recovery. After this page you can say, for each failure, what the SDK does, after how many seconds, and which state, event and end code your page gets.

The SDK repairs a broken stream by itself. Your page only shows the state. This page lists every failure the SDK watches for, one table each. All numbers are the engine's own constants, for engine 2.0.0-beta.2.

## Three terms

| Term | Meaning |
| - | - |
| **Signalling** | A WebSocket between the browser and the platform. The browser and your app use it to agree on the video connection. It also carries the queue position and the reason when the platform closes a session. |
| **Video connection** | The WebRTC connection that carries video, sound and input. It runs directly between the viewer and the app's server when the network allows it, and otherwise through a relay (A server that forwards the video when the viewer's network does not allow a direct path.). |
| **Session** | One run of your app for one viewer, with a session ID and a ticket. A session can survive a broken connection. |

Signalling and the video connection fail independently. Most of this page follows from that.

## Four kinds of repair

| Repair | What is replaced | The session and the app | States your page sees |
| - | - | - | - |
| **Soft redial** | Signalling only. The video connection is kept, and the last frames stay on screen. | Kept. | `reconnecting` → `streaming` |
| **Rebuild** | Signalling and the video connection. Same session ID, same ticket. | Kept. | `reconnecting` → `connecting` → `streaming` |
| **Rejoin** (a shared-session viewer, a Test locally session) | Signalling and the video connection, to the same room or dev session. | Kept. | `recovering` → `connecting` → `streaming` |
| **Fresh session** | Everything: a new session ID, a new streamer ID, a new ticket when the SDK can get one. | A **new app process**. The app's state is lost, and `launchParams` are sent again. | `recovering` → `connecting` → `streaming` |

When no repair works, the session ends. `ended` is final: your page calls `create()` again.

## All timers at a glance

| Timer | Value | What it limits |
| - | - | - |
| Reconnect window | 180 seconds. 10 minutes for a shared-session viewer and for a Test locally session. | All redials after a drop, counted from the first one. Reset when video plays again. |
| Wait before each redial | About 1, 2, 4, 8, then 15 seconds, each varied by 20 % up or down | So that many viewers do not redial in the same second. Never scheduled past the end of the window. |
| Dial | 15 seconds | Signalling must open after a dial. |
| Soft redial | 15 seconds | After signalling reopened, the renegotiated video must play. |
| Video connection "disconnected" | 6 seconds | How long a disconnected video connection may heal by itself. A "failed" one gets no wait. |
| Offline | 3 seconds | After the browser reported offline, how long the SDK waits for the signalling close event before it rebuilds. |
| No video frames | 10 seconds, checked every 2 seconds | A connected stream whose decoded-frame counter stands still. |
| Connect | 60 seconds | From the app's offer to video that plays. |
| Start | 210 seconds | After signalling opened: an offer or a queue position must arrive. |
| Blocked network | First verdict at 8 seconds, then every 2 seconds, until 30 seconds | After the app's offer was applied: are there any usable network paths? |
| Relay check | At connect, and once more 5 seconds later | Is the stream relayed over TCP or TLS? |
| Background on phones and tablets | 60 seconds | A hidden tab on iOS or Android ends the session. |
| Platform calls in `create()` | 10 seconds per call, up to 3 attempts | See [Errors and disconnects](https://docs.streampixel.io/resources/web-sdk-v2/errors-and-disconnects.md#errors-from-create). |

## Signalling drops

| Question | Answer |
| - | - |
| **What happened** | The signalling WebSocket closed without a close code (`1005`) or abnormally (`1006`). Typical causes: a network blip, a Wi-Fi switch, a signalling server restarting. The video connection is often still alive. |
| **What the SDK does** | It starts the reconnect window and waits about 1 second. If the video connection is still connected, it reopens **signalling only**, on the same session ID and ticket (soft redial). The app then renegotiates the video. If signalling does not open within 15 seconds, or the new video does not play within 15 seconds after it opened, the SDK rebuilds the whole connection on the same session. If the video connection was already gone, it rebuilds instead, after the same wait. |
| **What your page sees** | State `reconnecting` with `attempt` and `deadlineMs`. Then `streaming` after a soft redial, or `connecting` and then `streaming` after a rebuild. The state stays `reconnecting` until the new video really plays. No `session` event: the IDs are the same. No `stats` events while reconnecting. |
| **If it cannot be repaired** | `ended` with code `4007`, `endKind: 'error'`, at the first redial that falls due after the window has run out. That is shortly after 180 seconds, not exactly at it: a dial that is under way gets its 15 seconds first. |

> [accordion] Why the state stays reconnecting until video plays
>
> After signalling reopens, the app sets up a new video connection for the new socket, and the old video stops as soon as the app drops the old one. If the SDK reported `streaming` when signalling reopened, a failed renegotiation would leave your page showing `streaming` over a frozen picture. So `streaming` is reported when the new video plays, and the old video connection is closed only then: its last frame stays on screen until the new one takes over.

## The browser goes offline, or comes back

| Question | Answer |
| - | - |
| **What happened** | The browser fired its `offline` event, or later its `online` event. |
| **What the SDK does** | On `offline`, it closes the signalling socket only, without a close code, and keeps the video connection. The platform reads that as a drop and holds the session. The reconnect flow above starts at once, instead of after a network timeout. If the browser does not report the close within 3 seconds, the SDK rebuilds the connection on the same session. On `online`, when a redial is waiting, the remaining wait is skipped and the redial runs now. |
| **What your page sees** | The same as for a signalling drop: `reconnecting`, then `streaming`, or `connecting` and `streaming`. |
| **If it cannot be repaired** | `ended` with code `4007`, as above. |

> [!NOTE]
>
> The video connection is kept on purpose. Browsers sometimes report "offline" while video still flows: a Wi-Fi switch, a VPN. Closing the video connection then would make the app see the viewer leave and end the session.

## Signalling does not open

| Question | Answer |
| - | - |
| **What happened** | The SDK dialled signalling and the socket did not open within 15 seconds. Typical cause: something on the path accepts the connection and never answers. The browser's own timeout is a minute or more. |
| **What the SDK does** | It drops that dial and redials inside the reconnect window, with the waits listed above. This also applies to the very first dial after `create()`. |
| **What your page sees** | State `reconnecting`, then `connecting` for the next dial. On the first dial: `connecting` → `reconnecting` → `connecting`. |
| **If it cannot be repaired** | `ended` with code `4007`, `endKind: 'error'`. |

## The video connection dies

| Question | Answer |
| - | - |
| **What happened** | The stream was playing, signalling is still open, and the browser reports the video connection as **failed**, or as **disconnected** for more than 6 seconds. Typical causes: the relay went away, a firewall dropped the flow, the app's side closed its end. Nothing closes, so without this check the picture would stay frozen. |
| **What the SDK does** | A "failed" connection is handled at once. A "disconnected" one gets 6 seconds to heal by itself. Then the SDK drops signalling **without a close code**, so that the platform reads a drop and holds the session, and rebuilds the connection on the same session ID and ticket after the usual wait of about 1 second. A shared-session viewer rejoins its room instead. |
| **What your page sees** | State `reconnecting` → `connecting` → `streaming`, with the `progress` events of a normal start. A shared-session viewer: the `stalled` event, then `recovering` → `connecting` → `streaming`. No `session` event: the IDs are the same. |
| **If it cannot be repaired** | `ended` with code `4007`, `endKind: 'error'`, when the reconnect window runs out. A shared-session viewer: code `4102` after three rejoins. |

This check only runs while the state is `streaming` or `awaitingPlay`. Before the first frame, the connect limit below decides.

## Connected, and no video frames

| Question | Answer |
| - | - |
| **What happened** | The video connection reports that it is connected, and no new frame was decoded for 10 seconds. Typical cause: the app hung or stopped rendering while its connection stayed up. |
| **How it is measured** | Every 2 seconds the SDK reads the browser's count of decoded frames. When the count has not moved for 10 seconds, the check fires, once. It only judges a connection that reports connected. It does not judge while the tab is hidden: a hidden tab may stop decoding while the stream is fine. |
| **What the SDK does** | It fires `stalled` with a diagnostics snapshot. Then it starts **one fresh session**: a new session ID, a new streamer ID (an ID you chose with `advanced.streamerId` is kept), and a new ticket when the SDK can get one. A second stall on the same stream object ends the session. |
| **What your page sees** | Event `stalled`. State `recovering` with `attempt: 1`, then `connecting`, then `streaming`. The `session` event fires again with the new IDs. |
| **If it cannot be repaired** | `ended` with code `4102`, `endKind: 'error'`. |

The fresh session is given **once per stream object**. The count is not reset when the new session plays.

| Who | Instead of a fresh session |
| - | - |
| The host of a shared session | The session ends with `4102` at the first stall. A fresh app would restart the room under every viewer. |
| A viewer of a shared session | Rejoins the room, up to 3 times (`recovering` with `attempt` 1 to 3). The count starts again when video plays. Then `4102`. |
| A Test locally session | Rejoins the same dev session, up to 3 times. There is only your own Unreal. Then `4102`. |

> [accordion] Which ticket does a fresh session use?
>
> | How the stream got in | The fresh session |
> | - | - |
> | Public project, or a password | The SDK requests a new ticket. The password is held in memory for this stream object only. |
> | Single sign-on | The sign-in grant was single-use, so the first ticket is presented again. |
> | "Your app only" (not available yet), with a ticket function | The SDK calls your function again, with `reason: 'recovery'`. |
> | "Your app only" (not available yet), with a fixed ticket | The first ticket is presented again. |

## The video never starts

| Question | Answer |
| - | - |
| **What happened** | The app's offer arrived, and 60 seconds later the state is still `connecting`. Either the video connection never came up (the viewer's network or the app's server), or it came up and no first frame arrived (the app hung before it sent video). |
| **What the SDK does** | The same as for a stall: `stalled`, then one fresh session, or a rejoin for a shared-session viewer and a Test locally session. |
| **What your page sees** | Event `stalled`. State `recovering` → `connecting` → `streaming`. |
| **If it cannot be repaired** | `ended` with `endKind: 'error'`. Code `4101` when the video connection never came up. Code `4102` when it was connected and no video arrived. |

The two codes exist so that the end points to the right place: `4101` to the network between the viewer and the stream, `4102` to the app.

## A network that blocks the stream

| Question | Answer |
| - | - |
| **What happened** | After the app's offer, the browser looked for network paths and found only local addresses: no public address and no relay address. The stream is not connected. This is the pattern of a corporate firewall that blocks WebRTC. |
| **What the SDK does** | It looks 8 seconds after the offer was applied. It gives the verdict only when the browser has finished looking for paths. While the browser is still looking, a slow relay is not a blocked network: the SDK looks again every 2 seconds, until 30 seconds after the offer. After that it stops judging, and the 60-second connect limit above takes over. On a verdict the session ends at once. There is no retry and no fresh session. |
| **What your page sees** | `ended` with code `4100`, `endKind: 'network-blocked'`. No `stalled` event. The `message` tells the viewer to ask their IT team or try another network. |

A stream that connects over local addresses only, on the same local network, is never judged blocked.

Point the viewer's IT team to [Network requirements](https://docs.streampixel.io/resources/concepts/network-requirements.md).

## Relay fallback

| Question | Answer |
| - | - |
| **What happened** | UDP is blocked on the viewer's network. The stream works, relayed over TCP or TLS, at lower quality. |
| **What the SDK does** | When the video connection is up, it reads which path the browser selected. If that path is a relay over TCP or TLS, it fires `relayFallback`. If not, it checks once more 5 seconds later: the path can move to TCP moments after the connection came up. It changes nothing in the stream. |
| **What your page sees** | Event `relayFallback` with `transport` (`'tcp'` or `'tls'`) and `showWarning`, which is the project's "UDP blocked warning" setting. The state stays `streaming`. `stats.relayTransport` shows the transport every second: `''` on a direct path, `'udp'`, `'tcp'` or `'tls'` on a relay. |

```ts theme={"dark"}
stream.on('relayFallback', ({ transport, showWarning }) => {
  if (showWarning) showNotice(`Your network blocks UDP. The stream is relayed over ${transport.toUpperCase()} and may look less sharp.`);
});
```

> [!TIP]
>
> `@streampixel/ui` shows this notice for you, when the project's setting is on. See [Ready-made screens](https://docs.streampixel.io/resources/web-sdk-v2/ui-overlays.md).

> [accordion] Forcing the relay
>
> The SDK forces the relay only when `advanced.iceTransportPolicy` is `'relay'`, or when the project's "force TURN" setting is on. Otherwise the browser chooses the best path that works, and uses the relay when no direct path does.
>
> When the relay is forced and the platform handed out no relay, the session ends with code `4010`, `endKind: 'server'`.

## The app stops, or never starts

These are decided by the platform, or by the SDK when the platform stays silent. None of them is retried for a normal session: a stopped app cannot be reconnected to.

| What happened | What the SDK does | What your page sees |
| - | - | - |
| The app closed or crashed during the session. The platform closes with `4006`. | Ends the session. | `ended`, code `4006`, `endKind: 'server'` |
| The app took too long to start, no server was free, the app was not found, or it reported an error. The platform closes with `4005`, `4001`, `4002` or `4003`. | Ends the session. | `ended` with that code, `endKind: 'server'` |
| The app hung and its connection stayed up. | See [Connected, and no video frames](#connected-and-no-video-frames). | `stalled`, `recovering` |
| Signalling accepted the viewer, and then sent no offer and no queue position for 210 seconds. | Ends the session. This limit is above the platform's own limits for this phase, so the platform's code wins whenever the platform answers. It only ends a wait the platform has forgotten. Not applied while queued, to a shared-session viewer, or to a Test locally session. | `ended`, code `4104`, `endKind: 'error'` |
| The SDK could not build the connection from what the platform sent: no signalling host, or a relay list or an offer the browser refuses. | Ends the session at once. | `ended`, code `4103`, `endKind: 'error'` |
| Access was refused on signalling: `1008` or `4401`. | Ends the session. The same ticket would be refused again. | `ended` with that code, `endKind: 'server'` |

## Shared sessions and Test locally

Three cases recover differently from a normal session.

| | Normal session, shared-session host | Shared-session viewer | Test locally session |
| - | - | - | - |
| Reconnect window | 180 seconds | 10 minutes | 10 minutes |
| `waitingForHost` in `reconnecting` | Not set | `true` | `true` |
| A platform close that is not a drop and not final | Ends with the platform's code | Rebuilds and waits for the host | `4006` rebuilds and waits for Unreal. Other codes end. |
| No video frames | One fresh session. The host: ends. | Rejoin, up to 3 times | Rejoin, up to 3 times |
| The video connection dies | Rebuild | Rejoin | Rebuild |
| Start limit of 210 seconds | Applies | Not applied | Not applied |

The final closes end every kind of session: `1008`, `4401`, and the platform's reasons project inactive, no worker available, application not found, application error, maximum runtime reached, no streamer connected and relay unavailable.

See [Shared sessions](https://docs.streampixel.io/resources/web-sdk-v2/shared-sessions.md) and [Test locally](https://docs.streampixel.io/resources/web-sdk-v2/test-locally.md).

## Ends that are not failures

| What happened | What the SDK does | What your page sees |
| - | - | - |
| No input for the idle time. | Fires `afkWarning` during the countdown, then ends the session. | `ended`, code `1000`, `endKind: 'afk'` |
| A phone or tablet (iOS or Android) left the tab hidden for 60 seconds. | Ends the session, so that a phone in a pocket does not hold a GPU. Coming back within 60 seconds cancels it. `advanced.flags.backgroundDisconnect: false` turns this off. | `ended`, code `1000`, `endKind: 'afk'` |
| Any tab becomes hidden. | Releases held keys and mouse buttons. The no-video check pauses. | Nothing |

## What this means for your page

* **Show the state, do not repair.** Do not build your own reconnect on top. Do not call `reconnect()` on Epic's object (`stream.pixelStreaming`): the SDK owns reconnection.
* **Use `deadlineMs` for a countdown.** It is the time, in epoch milliseconds, at which the reconnect window ends.
* **Expect `session` to fire again.** After a fresh session, `currentSessionId` and `currentStreamerId` are new. If you store them, update them.
* **Expect your app to restart once.** After a fresh session, the app starts from the beginning and receives `launchParams` again. Its earlier state is lost.
* **Listeners survive.** Listeners added with `stream.on()` and `stream.addEventListener()` stay attached through every repair. Epic's object itself is replaced on a rebuild: read `stream.pixelStreaming` each time you use it.
* **After `ended`, create again.** No repair happens after `ended`.

```ts reconnect-banner.ts theme={"dark"}
stream.on('state', (s) => {
  if (s.kind === 'reconnecting') {
    const secondsLeft = Math.max(0, Math.round((s.deadlineMs - Date.now()) / 1000));
    showBanner(s.waitingForHost ? 'Waiting for the host…' : `Reconnecting… (${secondsLeft} s left)`);
  } else if (s.kind === 'recovering') {
    showBanner('Restarting the stream…');
  } else if (s.kind === 'streaming') {
    hideBanner();
  }
});
```

More patterns for banners and status screens are in the [cookbook](https://docs.streampixel.io/resources/web-sdk-v2/cookbook.md).

## Next steps

> [card] [Diagnostics](https://docs.streampixel.io/resources/web-sdk-v2/diagnostics.md)
>
> Read `stats` and `getDiagnostics()`, and find out why one session went wrong.

> [card] [The engine and updates](https://docs.streampixel.io/resources/web-sdk-v2/engine-and-updates.md)
>
> How the code that does all this reaches the page.

> [card] [Events and states](https://docs.streampixel.io/resources/web-sdk-v2/events-and-states.md#reconnection-and-recovery)
>
> Reference: the states and events named on this page, with their fields.

> [card] [Errors and disconnects](https://docs.streampixel.io/resources/web-sdk-v2/errors-and-disconnects.md#how-a-session-ends)
>
> Reference: every end code and the sentence shown to the viewer.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.