Skip to main content
Advanced For developers who ship a page to production. After this page you can handle every failure before a stream starts, tell why a session ended, show the viewer the right sentence, and collect what support needs. A stream can fail at two moments. Your page handles them in two places.
A password is neither of the two. On a password project create() resolves, and the stream waits in the state awaitingPassword. A wrong password comes back as that state with wrong: true. See Access.

The short version

This handler covers both moments. The sections below explain every branch.
handle-errors.ts

Errors from create()

create() rejects with one of four errors. AuthError and EngineLoadError are exported by @streampixel/web-sdk, so instanceof works. A full handler for the kinds a viewer can meet:
create-errors.ts
Aborting signal during a platform call rejects at once. Aborting during the engine download rejects as soon as the download has finished or failed.

AuthError

Every AuthError has these properties:
string
required
The category. Switch on it. The table below lists every kind. A newer engine may add a kind this page does not list yet, so keep a default branch.
string
required
A description. For sso-failed it is one of a fixed set of sentences written for the viewer. For the other kinds, treat it as text for your logs.
number
The HTTP status, when the platform answered.
object
The project’s logo, banner, loading texts and theme. Present once the project is known, so your own offline or sign-in screen can look like the project.
string
For sso-required and sso-failed: navigate here to start the sign-in (again).
string
For sso-failed: the sign-in service’s error code. For logs only.
number
For rate-limited: seconds until another attempt is accepted, when the platform said.
boolean
For rate-limited: true means every attempt from this network is refused for now, not only wrong passwords.
All kinds:
stream.submitPassword() rejects with the same AuthError for failures that are not about the password itself (kind network, project-offline and so on). A wrong password does not reject: it resolves, and the state is awaitingPassword with wrong: true.

EngineLoadError

The package you install is a small loader. The engine is downloaded when create() runs, from js.streampixel.io or its mirror js-backup.streampixel.io, and verified. When no verified engine can be loaded, create() rejects with EngineLoadError and no stream starts: the npm package holds no copy of the engine to fall back to. A failed load is not remembered, so calling create() again tries again. err.reason says why. The first group is what you can fix in your page or on the viewer’s network: The second group means the list of engine builds (the manifest) failed one of the loader’s checks and was refused. Your page cannot fix these. If one repeats, contact support with the reason. How the loader finds, checks and loads the engine is described in The engine and updates.

TypeError

Option mistakes are reported before any network call. The message names the option. All options are listed in Options.

AbortError

When you pass signal and abort it before create() resolves, create() rejects with a DOMException named AbortError. Nothing is left running: no session, no GPU. Aborting after create() resolved destroys the stream instead, and ended fires with endKind: 'user'.

How a session ends

Once a stream exists, every ending arrives the same way: the ended event, and the state ended with the same fields.
number
required
The end code. The tables below list every code. DisconnectCodes exports the names.
string
required
The server’s own text, or the SDK’s description. For logs and support, not for viewers.
'user' | 'afk' | 'server' | 'error' | 'network-blocked'
required
Who ended the session. See the next table.
string
required
A sentence in plain language for the viewer. It is the same wording as Streampixel’s share page.
ended is final. A stream that ended has no connect() or reconnect(), and all its listeners are removed after ended has fired. To start again, call destroy() and then create() again. See Start again.

Codes sent by the platform

Notes on this table:
  • 1005 and 1006 (ABNORMAL) are connection drops. They never end a session by themselves: the SDK reconnects, and ends with 4007 when that fails.
  • 4010 is also decided by the SDK itself when the project forces the relay and the platform handed out none. The endKind is server in both cases.
  • A Test locally session that expired ends with 1008 and its own sentence: “This dev session has expired or is not valid any more. Start a new one in the dashboard (Test locally).”
  • For causes and fixes on the platform side, see Disconnect codes.

Codes decided by the SDK in the browser

The platform never sends these. They mean the cause is on the viewer’s side of the connection, or between the viewer and the platform. There is nothing to look for in your application’s logs.
DisconnectCodes.SESSION_TERMINATED is a deprecated second name for 4000. Use PROJECT_INACTIVE for 4000 and SESSION_TERMINATED_BY_PLATFORM for 4009.

What the SDK retries, and what ends the session

The exact timings are in Reliability. What your page sees while the SDK recovers is in Events and states.

What to show the viewer

The SDK already wrote the sentence: show message. Then decide what to offer next to it.
@streampixel/ui draws this end screen for you, with the sentence and one button. See Ready-made screens.

Start again

start-again.ts
destroy() on a live stream fires ended with code 1000 and endKind: 'user' before it drops the listeners. That is why the listener returns early for user: without the check, a restart would show an end card for the stream you just replaced. This example leaves out the try / catch around create() shown in The short version.

What to send to support

Collect these four things. The first three are available at any time after create() resolved.
1

The session's IDs

stream.currentSessionId and stream.currentStreamerId. They are the IDs in your Streampixel analytics. The session event announces them, also when the SDK moves to a fresh session.
2

The engine version

stream.engineVersion. The engine updates by itself, so it can differ from the package version you installed.
3

The end

The ended payload: code, reason and endKind.
4

A connection snapshot

await stream.getDiagnostics(), taken while the stream is still up. After the end it returns null. The stalled event carries the same kind of snapshot at the moment the video stopped.
support-report.ts
A snapshot from getDiagnostics() holds the viewer’s network addresses. Send it to support, do not publish it. See Diagnostics.
Send the report to support@streampixel.io.

Common questions

That is expected. destroy() ends a live session, so ended fires with code 1000 and endKind: 'user', and then the listeners are dropped. Check endKind, or unsubscribe before you call destroy(). stream.on() returns the function that unsubscribes.
The platform closed the session cleanly. Your page did not end it: disconnect() and destroy() give endKind: 'user'. The message is “The stream was disconnected.”
ended belongs to a stream object, and a rejected create() returned none. Handle the error in the catch.
4102 means the connection was up and no video frames arrived, also after the SDK tried one fresh session. The usual cause is the application: it stopped rendering or hung. Look at the application, not at the viewer’s network. 4101 is the code for a video connection that never came up.
The network allows neither a direct path nor the relay. Show the sentence, and point the viewer’s IT team to Network requirements.

Next steps

Reliability

One level up: what the SDK does for each failure, with the exact timings.

Diagnostics

Read stats and getDiagnostics(), and debug a bad session.

Events and states

Every state and event, with its fields.

Stream API

Reference: every property and method of the stream object.