Skip to main content
Version: v1.12.0

Error Handling

This section is an overview of error conditions, how the Web Broadcast SDK reports them to the application, and what an application should do when those errors are encountered. There are four categories of errors:

try {
  stage = new Stage(token, strategy);
} catch (e) {
  // 1) stage instantiation errors
}

try {
  await stage.join();
} catch (e) {
  // 2) stage join errors
}

stage.on(StageEvents.STAGE_PARTICIPANT_PUBLISH_STATE_CHANGED, (participantInfo, state) => {
  if (state === StageParticipantPublishState.ERRORED) {
    // 3) stage publish errors
  }
});

stage.on(StageEvents.STAGE_PARTICIPANT_SUBSCRIBE_STATE_CHANGED, (participantInfo, state) => {
  if (state === StageParticipantSubscribeState.ERRORED) {
    // 4) stage subscribe errors
  }
});

Stage Instantiation Errors​

Stage instantiation does not remotely validate tokens, but it does check for some basic token issues that can be validated on the client-side. As a result, the SDK may throw an error.

Malformed Participant Token​

This occurs when the stage token is malformed. When instantiating a Stage, the SDK throws an error with this message: "Error parsing Stage Token."

Action: Create a valid token and retry instantiating.

Stage Join Errors​

These are the errors that may occur when initially attempting to join a stage.

Stage was Deleted​

This occurs when joining a stage (associated with a token) which was deleted. The join SDK method throws an error with this message: "Operation timed out."

Action: Create a valid token with a new stage and retry joining.

Expired Participant Token​

This occurs when the token is expired. The join SDK method throws an error with this message: "Token expired and is no longer valid."

Action: Create a new token and retry joining.

Invalid or Revoked Participant Token​

This occurs when the token is not valid or was revoked/disconnected. The join SDK method throws an error with this message: "Operation timed out."

Action: Create a new token and retry joining.

Disconnected Token​

This occurs when the stage token is not malformed but is rejected by the Stages server. The join SDK method throws an error with this message: "Operation timed out."

Action: Create a valid token and retry joining.

Network Errors for Initial Join​

This occurs when the SDK cannot contact the Stages server to establish a connection. The join SDK method throws an error with this message: "Operation timed out."

Action: Wait for the device’s connectivity to recover and retry joining.

Network Errors when Already Joined​

If the device’s network connection goes down, the SDK may lose its connection to Stage servers. You may see errors in the console because the SDK can no longer reach backend services. POSTs to https://broadcast.stats.live-video.net will fail.

If you are publishing and/or subscribing, you will see errors in the console related to attempts to publish/subscribe.

Internally the SDK will try to reconnect with an exponential backoff strategy.

Action: Wait for the device’s connectivity to recover. If publishing or subscribing, refresh the strategy to ensure republication of your media stream(s).

Publish and Subscribe Errors​

Publish Error: Publish States​

The SDK reports ERRORED when a publish fails. This can occur due to network conditions or if a stage is at capacity for publishers.

stage.on(StageEvents.STAGE_PARTICIPANT_PUBLISH_STATE_CHANGED, (participantInfo, state) => {
  if (state === StageParticipantPublishState.ERRORED) {
      // Handle
  }
});

Action: Refresh the strategy to attempt republication of your media stream(s).

Subscribe Errors​

The SDK reports ERRORED when a subscribe fails. This can occur due to network conditions or if a stage is at capacity for subscribers.

stage.on(StageEvents.STAGE_PARTICIPANT_SUBSCRIBE_STATE_CHANGED, (participantInfo, state) => {
  if (state === StageParticipantSubscribeState.ERRORED) {
    // 4) stage subscribe errors
  }
});

Action: Refresh the strategy to try a new subscribe.