> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://fastpix.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fastpix.com/docs/_mcp/server.

# Handle playback errors

> Learn how to detect and respond to playback errors in the FastPix Android Player.

Learn how to detect and respond to playback errors in the FastPix Android Player.

## Listen for errors

The `PlaybackListener` interface includes an `onError` callback that fires when a playback or validation error occurs. Attach the listener to your player to capture errors:

```kotlin
val listener = object : PlaybackListener {
    override fun onError(error: PlaybackException) {
        // Handle the error
        Log.e("Player", "Playback error: ${error.message}")
    }

    override fun onPlay() {}
    override fun onPause() {}
    override fun onPlaybackStateChanged(isPlaying: Boolean) {}
}
player?.addPlaybackListener(listener)
```

## Validation errors

When you call `setFastPixMediaItem`, the SDK validates the configuration before starting playback. If validation fails (for example, an empty `playbackId`), the method returns `false` and the error details arrive through `PlaybackListener.onError()`.

```kotlin
val ok = player?.setFastPixMediaItem {
    playbackId = "YOUR_PLAYBACK_ID"
} ?: false

if (!ok) {
    // Validation failed, error details arrive via onError callback
}
```

## Common error scenarios

* **Empty or invalid playback ID**: The SDK can't resolve the stream URL.
* **Invalid stream type**: `streamType` must be `on-demand` or `live-stream`.
* **Expired or invalid playback token**: Secure streams reject the request if the token has expired or is malformed.
* **Network issues**: Unstable connections cause buffering or playback failures. Use `onBufferingStart` and `onBufferingEnd` callbacks to show appropriate UI.
* **Unsupported format**: The stream uses a format or codec not supported by the device.

#### Frequently asked questions

Attach a `PlaybackListener` and implement `onError(error: PlaybackException)`. It fires whenever a playback or validation error occurs, and `error.message` describes what went wrong.

`setFastPixMediaItem` returns `false` when validation fails, for example an empty `playbackId`. The error details also arrive through the `PlaybackListener.onError()` callback, so listen there as well.

Common causes are an empty or invalid playback ID, an invalid stream type, an expired or invalid playback token, network issues, and a format or codec the device does not support.

Use the `onBufferingStart` and `onBufferingEnd` callbacks to show and hide a loading spinner while an unstable connection buffers, rather than treating every stall as a hard error.

## What's next

* [Listen to playback events](/docs/android-player/listen-to-playback-events) for buffering, seek, and completion callbacks.
* [Play uploaded videos](/docs/android-player/play-uploaded-videos) to set a media item with `setFastPixMediaItem`.
* [Enable secure video playback](/docs/android-player/enable-secure-video-playback) to avoid token errors on protected streams.