Skip to main content
Version: v1.17.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. Errors are reported by the SDK to listeners of the StageEvents.ERROR event:

stage.on(StageEvents.ERROR, (error: StageError) => {
// log or handle errors here
console.log(`${error.code}, ${error.category}, ${error.message}`);
});

Stage Errors

A StageError is reported when the SDK encounters a problem it cannot recover from and generally requires app intervention and/or network reconnection to recover.

Each reported StageError has a code (or StageErrorCode), message (string), and category (StageErrorCategory). Each is related to an underlying operation category.

The operation category of the error is determined based on whether it is related to the connection to the stage (JOIN_ERROR), sending media to the stage (PUBLISH_ERROR), or receiving an incoming media stream from the stage (SUBSCRIBE_ERROR).

The code property of a StageError reports the specific problem:

NameCodeRecommended Action
TOKEN_MALFORMED1Create a valid token and retry instantiating the stage.
TOKEN_EXPIRED2Create an unexpired token and retry instantiating the stage.
TIMEOUT3The operation timed out. If the stage exists and the token is valid, this failure likely is a network issue. In that case, wait for the device’s connectivity to recover.
FAILED4A fatal condition was encountered when attempting an operation. Check error details. If the stage exists and the token is valid, this failure likely is a network issue. In that case, wait for the device’s connectivity to recover.
CANCELED5Check application code and ensure there are no repeated join, refreshStrategy, or replaceStrategy invocations, which may cause repeated operations to be started and canceled before completion.
STAGE_AT_CAPACITY6Try the operation again when the stage is no longer at capacity, by refreshing the strategy.
CODEC_MISMATCH7The codec is not supported by the stage. Check the browser and platform for codec support. For IVS real-time streaming, browsers must support the H.264 codec for video and the Opus codec for audio.
TOKEN_NOT_ALLOWED8The token does not have permission for the operation. Recreate the token with the correct permission(s) and try again.

Handling StageError Example

Use the StageError code to determine if the error is due to an expired token:

stage.on(StageEvents.ERROR, (error: StageError) => {
if (error.code === StageError.TOKEN_EXPIRED) {
// recreate the token and stage instance and re-join
}
});

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.

Errored States

We recommend you use these states for application logging and to display messaging to users that alerts them of connectivity issues to the stage for a particular participant.

Publish

The SDK reports ERRORED when a publish fails.

stage.on(StageEvents.STAGE_PARTICIPANT_PUBLISH_STATE_CHANGED, (participantInfo, state) => {
if (state === StageParticipantPublishState.ERRORED) {
// Log and/or display message to user
}
});

Subscribe

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) {
// Log and/or display message to user
}
});