Troubleshooting Errors

Introduction

Playback errors can occur for a variety of reasons — from unsupported media formats and network interruptions to device-specific decoder limitations.
The Bitmovin Android Player SDK provides a structured way to detect, diagnose, and handle these errors, allowing your app to recover gracefully and maintain a reliable playback experience.

This page explains how errors are surfaced through the SDK, how to interpret them, and which tools you can use to collect diagnostic information.
For information on specific errors, please see

Decoder Errors — hardware and codec issues

By following the recommendations in this section, you can quickly identify the root cause of playback interruptions, apply safe workarounds, and gather the right information to share with Bitmovin Support when needed.

How Errors Are Surfaced

In the Bitmovin Android Player SDK, errors are emitted as events through one of three event emitters:

Player — playback related errors as well as all errors for the current active Source
Source — media source and manifest-related errors
OfflineContentManager — offline download errors

All emitters implement the EventEmitter<T : Event> interface, which allows you to subscribe to specific event types.

Listening for Errors

Errors are exposed as PlayerEvent.Error, SourceEvent.Error and OfflineEvent.Error . The event itself contains the error code, a message with further details describing the error and a data field containing additional details about the error. In most cases the data field contains an Exception.

data class Error(
    val code: PlayerErrorCode,
    val message: String,
    val data: Any? = null
) : PlayerEvent, ErrorEvent

Example usage:

player.on<PlayerEvent.Error> { error ->
    Log.e("Bitmovin", "Error ${error.code}: ${error.message}")
}

After an error is emitted by the Player or Source, the current playback session is unloaded automatically.
Your app should handle this by showing an error message or reinitializing playback as appropriate. When using the Bitmovin Player UI, a default error screen will be displayed until a new source is loaded.