Troubleshooting and Error Handling


In this guide we will explain how to debug and troubleshoot exceptions occurring in the Roku SDK as well as helping you understand the different error codes and how to interpret them.


Connecting to the debugging console

To debug on Roku you will first have to connect to the debugging console through a shell application or the terminal.
Note that most IDEs that support Roku development have this feature built in, so if you are using one you can skip this step.

telnet roku-ip-address 8085

For a full list of debugging commands for the Brightscript console check out the Roku Documentation regarding debugging code.

Errors in the Roku SDK

What happens when an error occurs

When an error in the Roku SDK happens the error field on the BitmovinPlayer node is being populated.
To always be informed in case an error happens you should set up an event listener for this field.

m.bitmovinPlayer.ObserveField(m.BitmovinFields.ERROR, "catchVideoError")
sub catchVideoError()
  print "ERROR: "; m.bitmovinPlayer.error.code.toStr() + ": " + m.bitmovinPlayer.error.message
end sub

Error event

The error event thrown by the bitmovin player is made up of four properties:

  • name - Name of the error that has been thrown.
  • message - Error message containing details about the error.
  • code - Error code of the thrown error
  • data - Contains all the error fields from the native Roku video node.

Check out the full documentation of the bitmovin player error event here.

Understanding Error Codes


An unknown error is quite tricky to deal with because it is hard to guess what could have cause it. In this case it is best to check the data field on the error event. This field is used to collect all the error fields from Roku directly. The diagnostic error fields data.errorStrand data.errorInfo provide further context on the nature of the error. For more information about the Roku error fields check out the Roku Documentation.


This error is thrown when there was an issue with your Bitmovin player license, for example your license key is invalid. Check if the correct license key was set either in your manifest or the bitmovin player config.
Note: A SETUP_LICENSE_ERROR will destroy the bitmovin player


A source invalid error is thrown in case load was called with an invalid source object, be that a bitmovin source config or a content node. Be sure to check your config and make sure all required properties are set. For more information about the source config check out our documentation.


A playback error occurs when the stream passed with the source config has an unknown or unsupported format. To check which formats are supported by Roku check their Streaming specifications.


A network error happens when the stream passed in the source config could not be downloaded. This can have multiple reasons. For example the connection timed out, the server is down, unresponsive or unreachable. Make sure your devices is connected to the internet and the stream is available.


A DRM error happens when there was a problem with the DRM licensing call. Make sure the correct DRM provider and authentication token is set in the drmsection of the source config. Check out our documention for more information.

For more information regarding an error it is best to look at data property of the errorevent. This property contains all error related events thrown by Roku directly. For more information about Rokus error fields check out their official documentation.