> 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 display custom error UI when playback fails in the FastPix Flutter Player.

Learn how to display custom error UI when playback fails in the FastPix Flutter Player.

The FastPix Flutter Player lets you define an `errorWidgetBuilder` to show meaningful messages and visuals when errors occur during playback.

## Define a custom error widget

Pass an `errorWidgetBuilder` to the `FastPixPlayer` widget. The builder receives the error message as a string and returns a widget to display:

```dart
FastPixPlayer(
  controller: controller,
  errorWidgetBuilder: (error) {
    return Container(
      color: Colors.black,
      child: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Icon(Icons.error, color: Colors.red, size: 48),
            SizedBox(height: 16),
            Text(
              'Playback Error',
              style: TextStyle(color: Colors.white, fontSize: 18),
            ),
            SizedBox(height: 8),
            Text(
              error,
              style: TextStyle(color: Colors.white70, fontSize: 14),
              textAlign: TextAlign.center,
            ),
          ],
        ),
      ),
    );
  },
);
```

## Check player state for errors

You can also check the player state programmatically to detect errors:

```dart
if (controller.currentState == FastPixPlayerState.error) {
  // Handle error state
}
```

## Common error scenarios

* **Invalid playback ID**: The SDK can't resolve the stream URL. Verify that the ID is correct and case-sensitive.
* **Expired or invalid token**: Secure streams reject the request if the JWT token has expired or is malformed.
* **Network issues**: Unstable connections cause buffering or playback failures.
* **Unsupported format**: The stream uses a format not supported by the device.