Errors

Playback can fail for many reasons — network issues, DRM problems, malformed manifests. This page explains how PRESTOplay reports errors, what information they carry, and how to handle the errors you’re most likely to run into during development.

The Error object

The player triggers an error event or rejects a promise when an error occurs. If an API call returns a promise, the promise is rejected; otherwise, an error event is triggered. Every error is an instance of Error.

Errors are grouped into categories. The Error.category property holds one of the following values:

clpp.Error.Category.NETWORK   // Errors from the network stack.
clpp.Error.Category.TEXT      // Errors parsing text streams.
clpp.Error.Category.MEDIA     // Errors parsing or processing audio or video streams.
clpp.Error.Category.MANIFEST  // Errors parsing the manifest.
clpp.Error.Category.STREAMING // Errors related to streaming.
clpp.Error.Category.DRM       // Errors related to DRM.
clpp.Error.Category.PLAYER    // Miscellaneous errors from the player.
clpp.Error.Category.PLUGIN    // Errors thrown by plugins.
clpp.Error.Category.ADS       // Errors related to ads.

An error might be recoverable. The Error.severity property holds one of the following values:

// The player will try to recover from this error. If retrying continues to
// fail, the player might still issue a FATAL error. A failing download is a
// good example: the first failure might be reported as RECOVERABLE, but if
// the download keeps failing, the error turns into a FATAL one.
clpp.Error.Severity.RECOVERABLE

// A fatal error the player can't recover from. This usually stops playback
// and loading — release the player before you try again.
clpp.Error.Severity.FATAL

Use the unique Error.code property to identify an error. The full list of error codes is available in the API documentation. Extra data, such as an HTTP status code, is accessible through Error.data.

Error codes

See Error.Code for the full list of error codes.

A newer set of error codes conforming to a draft of the SVTA spec is also available under Error.svtaCode. These codes are subject to change until the SVTA spec is finalized.

Handling errors

Error event

Important

Attach an error listener immediately after instantiating the player. It’s safer and simpler than attaching it later.

player.on(clpp.events.ERROR, event => {
  const error = event.detail;
  // ...
});

Rejected promises

Add a catch handler to an asynchronous method:

const source = '//demo.cf.castlabs.com/media/prestodash/Manifest.mpd';
player.open({ source }).catch(error => {
  // ...
});

The same pattern works with other asynchronous methods, including:

• Player.play

• Player.pause

• Player.setPosition

• Player.release

• Player.destroy

Common video playback errors

Loading and playing a video involves several HTTP requests, and any of them can fail for reasons that have nothing to do with PRESTOplay itself. Here’s a quick reference for the issues developers run into most often.

Cross-origin resource sharing (CORS)

CORS errors occur when the player’s origin differs from the video’s origin (a different domain or port). Cross-origin requests are blocked by default. The browser console reports that the request was blocked by CORS policy.

To resolve CORS errors, configure the video server to allow the player’s origin. CORS errors commonly occur during development on localhost. A CORS browser extension or an HTTP proxy such as Charles or Fiddler can work around the issue temporarily during development. See CORS on MDN for details.

SSL issues

When using HTTPS, the video server must present a valid Secure Sockets Layer (SSL) certificate, or the request fails. The browser console reports an error such as net::ERR_CERT_AUTHORITY_INVALID (Chrome) or a similar code.

Common causes include:

• An expired SSL certificate

• A certificate not trusted by the browser

• A domain name mismatch between the certificate and the video server

• A revoked certificate

• A certificate issued by an untrusted certificate authority

Resolve SSL issues by ensuring the server presents a valid, unexpired certificate from a trusted authority.

Mixed content errors

A mixed content error occurs when the player is hosted on an insecure (HTTP) page and the video is hosted on a secure (HTTPS) server, or the other way around. Mixing HTTP and HTTPS requests, or making HTTPS requests from a page served over HTTP, is not allowed. The browser console reports a message such as “Mixed Content: The page was loaded over HTTPS.” See mixed content on MDN for details.

Serve the video player, videos, and other assets over HTTPS to avoid mixed content errors. These errors are easy to miss during development, since browsers commonly allow mixed content requests from localhost. As a temporary local workaround, you can allow insecure content in Chrome for a specific site.

Connectivity problems

A device can fail to connect to the internet, for example during a temporary outage. The browser console reports net::ERR_INTERNET_DISCONNECTED (Chrome). Check window.navigator.onLine in JavaScript to detect whether the browser is offline.

Network retry errors

Some network error events describe a failed request attempt, not the final playback result. When another attempt is available, the player continues with another request attempt or another URI for the same request. This commonly applies to manifest and segment requests with multiple possible URIs, such as DASH BaseURL, DASH Location, or content steering locations.

The request metadata in error.data.request describes the failed attempt:

player.on(clpp.events.ERROR, event => {
  const error = event.detail;
  const request = error.data && error.data.request;
  if (!request) {
    return;
  }

  console.log(request.uris[request.uriIndex], request.currentAttempt);
});

net.Request has more details about the request. The following properties are useful:

• request.currentAttempt: the number of attempts started for this request. On the first failed attempt, this is usually 1.

• request.maxAttempts: the maximum number of attempts allowed for this request.

• request.uris: the URIs that can be attempted for the request.

• request.uriIndex: the index in request.uris used by the failed attempt.

Other network error data can help identify the failure:

• error.data.url: the URL that failed.

• error.data.status: the HTTP status code, if one was received. For browser network failures where no HTTP response was available, this can be 0 or -1.

Use this metadata together with error severity. If the player can retry a failed network attempt, it reports the failed attempt with clpp.Error.Severity.RECOVERABLE. If all attempts fail, the final error is reported with clpp.Error.Severity.FATAL.

Control retry behavior with net.AttemptParameters in the manifest and streaming keys of PlayerConfiguration. See Player configuration for details.

Next topic: DRM

Previous topic: Events