Display Error Messages Plugin

Video Cloud
Brightcove Player
Player Developer
Troubleshooting/Error Handling

In this topic, you will learn how to modify the default error message behavior, create custom error messages and dispatch errors.


The error messages plugin allows the player to display user-friendly messages when it encounters an error. The default style sheet displays messages as a semi-transparent overlay on top of the video element itself. You can change existing message text and add your own styles. You can even create custom messages that are triggered when you want.

error message plugin

The error message shown in the image above was created by updating the player with an invalid src value in the sources property.

The error messages plugin is a default plugin and is automatically loaded with the Brightcove player. However, you can choose not to load it. Without this plugin, you will see a limited set of error messages and some errors will only appear in the browser console. For details on how to not load a default plugin when you create a player, see the Player Plugin Overview document.

Get started

It is best practice to update your player using the Brightcove Players module from Studio. This approach is used in the following sections to update the error messages plugin for your player. This will update all instances of your player. If you choose to update this plugin from a page of code, it will only affect that instance of your player

To update the plugin from your page code, first get a reference to the Brightcove player. In this example, in the JavaScript we are creating a variable named myPlayer and assigning it a reference to the player.

<video-js id="myPlayerID"
  class="video-js" controls></video-js>
<script src="https://players.brightcove.net/1507807800001/default_default/index.min.js"></script>
<script type="text/javascript">
    var myPlayer = this;

Standard errors

This plugin has a set of default error messages for the standard HTML5 video errors based on the runtime error code value:

  • Error code: 1
    • Headline: The video download was cancelled
    • Message: You aborted the media playback
  • Error code: 2
    • Headline: The video connection was lost, please confirm you're connected to the internet
    • Message: A network error caused the media download to fail part-way. Currently most helpful for MP4 and/or progressive download video formats. See the Known issues section in this document for details.
  • Error code: 3
    • Headline: The video is bad or in a format that can't be played on your browser
    • Message: The media playback was aborted due to a corruption problem or because the media used features your browser did not support.
  • Error code: 4
    • Headline: This video is either unavailable or not supported in this browser
    • Message: The media could not be loaded, either because the server or network failed or because the format is not supported.
  • Error code: 5
    • Headline: The video you're trying to watch is encrypted and we don't know how to decrypt it
    • Message: The media is encrypted and we do not have the keys to decrypt it.

If an error does not have an associated error code, a generic message is displayed:

  • Error code: unknown
    • Message: MEDIA_ERR_UNKNOWN
    • Description: An unanticipated problem was encountered, check back soon and try again

Override text

There are three parts of the error message that you can change:

  • headline : This is the message text at the top.
  • type : This is the Error Code: text.
  • message : This is the Technical details: text.
error message plugin

Once your player is created, in Studio edit the Plugins section of the Players module with a JSON object to set property values.

The example below shows how to override the message text for the standard error with an error code value of 4. The properties are defined as follows:

  • plugins: This property contains an array of properties and values. For this plugin, you only need to supply the name property with the value of errors.
  • options: This property is used to pass data to the plugin.
  • errors: This property defines the error code that you want to update. Here we are overriding the message text for the headline, type, and message.
  "errors": {
    "4": {
      "headline": "This is a custom error message",
      "type": "MEDIA_ERR_SRC_CUSTOM",
      "message": "These are the details for the custom message"

If you include the errors script in your code, you can override message text as follows:

  "errors": {
    "4": {
      "headline": "This is a custom error message",
      "type": "custom type",
      "message": "these are details"

Brightcove defined custom errors

Custom errors can also be defined. Brightcove has defined a number of custom errors, explained in this section, and you can also create custom errors, detailed in the next section.

  • Brightcove recommends custom error code values be a string. You will see two of the provided errors use negative numbers for historical reasons, but alpha-numeric/descriptive strings are less likely to cause collision issues.
  • Custom error messages can be named anything you want. Brightcove recommends that the type begin with PLAYER_ERR versus the standardized MEDIA_ERR to avoid confusion.
  • As detailed later in this section, you can make custom errors dismissible or not.

Five custom error messages have been added as a reference:

  • Error code: -1
    • Message: PLAYER_ERR_NO_SRC
    • Description: No video has been loaded
  • Error code: -2
    • Description: Could not download the video
  • Error code: Not set
    • Description: This video is restricted from playing on your current domain
  • Error code: Not set
    • Description: This video is restricted at your current IP address
  • Error code: Not set
    • Description: This video is restricted from playing in your current geographic region

User defined custom errors

When defining your own custom errors Brightcove recommends you do not use a code. (You see in the section above that this is what Brightcove is now doing with the newer custom errors they are defining.) You should also consider using the PLAYER_ERR_ prefix for your custom errors for consistency's sake, but of course you can name them however you wish.

This example creates a new user defined custom error message with an error code value of PLAYER_ERR_AGE_GATE and includes text based on an age gate test that you would enter in Studio's PLAYERS > PLUGINS section.

  "errors": {
      "headline": "You must be at least 18 years of age.",
      "message": "Content may be considered inappropriate for some users."

If you include the errors script in your code, you can add custom messages as follows:

videojs.getPlayer('myPlayerID').ready(function() {
  var myPlayer = this;
  //custom error
    "errors": {
        "headline": "You must be at least 18 years of age.",
        "message": "Content may be considered inappropriate for some users."

Displaying custom errors

When you define custom errors, you need to let Brightcove Player know when you want to display it. To do this, create your own code to determine when the message should be displayed. Then use the error() function to display the message as follows:

//display custom message
var age_appropriate = false;
myPlayer.on("loadstart", function () {
  if(!age_appropriate) {

Here the age_appropriate variable is set to false, but you would add your own code to determine when to display your custom error messages.

The error would be displayed to the user as follows:

user custom error message

Make custom errors non-dismissible

By default a custom error message is dismissible by the video viewer. As the following screenshot shows, there is an OK button to click to dismiss the window, as well as an X in the top right corner.

dismissible error message

If you wish to NOT permit the video viewer to dismiss the error message, you can do that. When you call the error() method, you can set the dismiss property to false.

myPlayer.error({code:'age-gate-error', dismiss: false});

When you do this the error message will appear as follows, with no way to dismiss the error.

not dismissible error message

getAll() method

You can use the getAll() method to see all the errors registered for a specific player. You can call the getAll() method anytime after the errors plugin has been initialized, for instance after player.errors() has been called. An example of calling the method is:


An example of the console display, with some errors expanded for details is:

getAll console display

Dispatch errors

In development you may wish to dispatch errors to test if your configuration changes are successful. You can do this using code similar to that shown in the following code snippet. In this case, a button is added to the code so you can dispatch the error at a chosen time.

<video-js id="myPlayerID"
  class="video-js" controls></video-js>
<script src="https://players.brightcove.net/1507807800001/default_default/index.min.js"></script>
<p><button onclick="changeVideo()">change video</button></p>
<script type="text/javascript">
  var changeVideo;
  videojs.getPlayer('myPlayerID').ready(function() {
    var myPlayer = this;
    changeVideo = function(){

Localize errors

The errors plugin supports multiple languages. To add language support, after the plugin has loaded load the particular language file you wish to use:

<script src="lang/es.js"></script>

You can then use the techniques shown in the Localizing Brightcove Player document to localize error messages.


It is possible that handling errors in the normal ready() section in the script block can cause issues. For instance, it can happen that the bc-catalog-error event could be dispatched before the player is ready, and if you listen for the error in the ready() section, you will not be able to handle the error. This issue can occur when using geo-filtering, a video is inactive, a video is out of scheduling range, or in a different account. You may find that there is not a problem in your code, but the issue can browser dependent, so use caution.

For example, here is plugin code that displays a message when a video is inactive:

videojs.registerPlugin('inactiveErrorCheck', function() {
  var myPlayer = this;
  myPlayer.one('bc-catalog-error', function(){
    var specificError;
      'errors': {
          'inactive-video-error': {
          'headline': 'The video you are trying to watch is inactive.',
          'dismiss': false
    if (typeof(myPlayer.catalog.error) !== 'undefined') {
      specificError = myPlayer.catalog.error.data[0];
      if (specificError !== 'undefined' & specificError.error_code == "VIDEO_NOT_PLAYABLE") {

Exaggerated error rate

If you are getting what seems like an unreasonable number of reported errors, it is important to know that you can get duplicate error events for the same session, creating this exaggerated error rate. Brightcove Player sends errors to analytics at the exact time, and in the same quantity, as they are reported to the player. For instance, if there is no media in a player, and code somehow calls play() one thousand times in a row, one thousand PLAYER_ERR_NO_SRC errors will be reported to analytics.

If there are a few sessions with tons of errors skewing the analytics, you should consider using the following logic to get a better sense of the actual issues:

number_of_sessions_with_errors / total_number_of_sessions
rather than
count of errors/number of views

Known issues

  • When playing back HLS sources, behavior after network connectivity is lost is probably not what you would expect. The details are:
    • In version 6.x of Brightcove Player HLS segments are endlessly requested and no MEDIA_ERR_NETWORK ever appears.
    • In version 5.x of Brightcove Player after a period of time (30+ seconds) a PLAYER_ERR_TIMEOUT error appears.
  • When loading videos in Edge on Windows 10 (both within the Studio and in public URLs), a MEDIA_ERR_SRC_NOT_SUPPORTED error is displayed and the video cannot be played.
  • On Android devices and iPhones, the tap events for error messages do not bubble up to the parent video element. This means that you can not close an error message once it appears. This behavior may be a problem if the user is in fullscreen mode, because they will have no way to leave this state.

    This issue is currently being worked on and should be fixed in a future player release. For now, you can try a work-around like this:

    player.on("touchstart", function(e) {
      if (player.error_) {


4 Oct 2018


  • Bug fix: Ignore progress events
  • Bug fix: Remove the postinstall script to prevent install issues
  • Updated to generator-videojs-plugin
  • Update rollup to version 0.66.0

23 Aug 2018


  • Using generator 7

3 Aug 2018


  • Babel the ES distribution by updating the generator
  • Package: Updated dependencies and enabled Greenkeeper

5 July 2018


  • Generator v6

8 May 2018


  • Added standard VERSION property

2 May 2018


  • Added timeout getter/setter
  • Dropped v5 support
  • Made the plugin ready for Video.js 7
  • Bug fix: Restart timeout monitor if playing when reinitialized
  • In documentation added usage of npm/bundler usage

13 Dec 2017


  • Added custom error for Flashls crossdomain errors
  • Added Czech translation
  • Added new custom errors and allow defining custom errors at runtime
  • Changed codes of recently-added errors, allow type and code to be shared, and add getAll() method
  • Fixed tests for Video.js 6
  • Resolved an issue where error events triggered on the player during contrib-ads playback would not be recognized
  • Now show spinner if player has stalled
  • Updated package browserify to version 13.3.0
  • Updated package karma to version 1.4.1
  • Updated package node-sass to version 4.5.0
  • Updated package npm-run-all to version 3.1.2
  • Updated package portscanner to version 2.1.1
  • Updated package shelljs to version 0.7.6
  • Added translations for some new strings
  • Updated tooling using generator v5 prerelease
  • Updated travis
  • Updates for Video.js 6.0 compatibility
  • Removed Bower support
  • Changed the codes of recently added errors so they will avoid collisions more reliably with 1.x implementations

6 Sep 2017


  • Added Czech translation
  • Resolved an issue where error events triggered on the player during contrib-ads playback would not be recognized

8 Jun 2017


  • Show spinner if player has stalled

22 May 2017


  • Added translations for some new strings

19 May 2017


  • Updated tooling using generator v5 prerelease
  • Removed Bower support

15 May 2017


  • Fixed some tooling issues, including missing distribution and language files

15 May 2017


  • Fixed mis-configured package.json fields

15 May 2017


  • Moved off of Spellbook for now and add pkg.module
  • Changed codes of recently-added errors, allow type and code to be shared, and add getAll() method

24 Apr 2017


  • Added option to disable watching progress events

19 Apr 2017


  • Fixed size detection to account for players that have no configured dimensions

18 Apr 2017


  • Added new custom errors and an extend method to customize errors at runtime

21 Feb 2017


  • Added support for Portuguese
  • Allow errors to be non-dismissible

9 Feb 2017


  • Removed deprecation warning about using videojs.plugin
  • Updated to build with Video.js 5 and 6

27 Feb 2017


  • Updated for Video.js 6.0 compatibility

7 Dec 2016


  • Displays error if Flash tech is unusable

11 Nov 2016


  • Cleanup event bindings when reinitialized

8 Sep 2016


  • Added in a user-friendly message for disabled Flash in IE

10 August 2016


  • Fixed close-button errors accessible message
  • Fixed typo in French translation

13 Apr 2016


  • Added listening for adtimeupdate
  • Added Arabic and Turkish

1 Mar 2016


  • Add Italian, Russian and Chinese (traditional and simplified)
  • Add English translations as a canonical template

11 Jan 2016


  • Bower

11 Jan 2016


  • Updated to use generator-videojs-plugin conventions

22 Nov 2015


  • Update to video.js 5.0

5 May 2015


  • Do not display errors when the player is paused or ended for timeouts
  • Fix a vdata exception when dispose is called

10 Sep 2014


  • Remove dist/ from .npmignore

3 Sep 2014


  • More localization improvements

27 Aug 2014


  • Fix /dist

27 Aug 2014


  • Localization improvements

19 Aug 2014


  • Localization

13 Jun 2014


  • Ended videos should not cause player timeouts on IE11/Win8rt

5 Jun 2014


  • Initial release