Handle playback errors

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:

1
FastPixPlayer(
2
  controller: controller,
3
  errorWidgetBuilder: (error) {
4
    return Container(
5
      color: Colors.black,
6
      child: Center(
7
        child: Column(
8
          mainAxisAlignment: MainAxisAlignment.center,
9
          children: [
10
            Icon(Icons.error, color: Colors.red, size: 48),
11
            SizedBox(height: 16),
12
            Text(
13
              'Playback Error',
14
              style: TextStyle(color: Colors.white, fontSize: 18),
15
            ),
16
            SizedBox(height: 8),
17
            Text(
18
              error,
19
              style: TextStyle(color: Colors.white70, fontSize: 14),
20
              textAlign: TextAlign.center,
21
            ),
22
          ],
23
        ),
24
      ),
25
    );
26
  },
27
);

Check player state for errors

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

1
if (controller.currentState == FastPixPlayerState.error) {
2
  // Handle error state
3
}

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.