Playback Error Handling in React Native Audio Pro SDK

React Native Audio Pro separates error reporting into two independent paths. A PLAYBACK_ERROR event is a non-fatal signal that something went wrong during playback — the player may still be usable and may retry on its own. A STATE_CHANGED event carrying state: AudioProState.ERROR is an unrecoverable failure: the player has been cleared and must be restarted. Understanding which path fired (and whether they appear together) is the foundation of a solid error-handling strategy.

Two Error Paths

1. `PLAYBACK_ERROR` Event

Emitted independently when a non-fatal error occurs. The player is not necessarily stopped — it may already be retrying. This is the right place to log the error, update UI, or attempt a URL refresh.

AudioPro.addEventListener((event) => {
  if (event.type === AudioProEventType.PLAYBACK_ERROR) {
    const { error, errorCode, recoverable, cause, index } = event.payload ?? {};
    console.warn('Playback error:', error, 'code:', errorCode);
  }
});

2. `STATE_CHANGED` with `state: AudioProState.ERROR`

Emitted when the player enters an unrecoverable failure and resets its internal state. After receiving this event you must re-load your queue and restart playback from scratch.

AudioPro.addEventListener((event) => {
  if (
    event.type === AudioProEventType.STATE_CHANGED &&
    event.payload?.state === AudioProState.ERROR
  ) {
    console.error('Player entered unrecoverable ERROR state');
    // Re-load your queue and call AudioPro.play() to restart
  }
});

PLAYBACK_ERROR and STATE_CHANGED: ERROR are independent — one does not imply the other. A PLAYBACK_ERROR with recoverable: true may fire without any accompanying state change, and an unrecoverable STATE_CHANGED: ERROR may arrive with or without a preceding PLAYBACK_ERROR. Always handle both.

`AudioProPlaybackErrorPayload`

The payload attached to a PLAYBACK_ERROR event contains the following fields:

Field	Type	Description
`error`	`string`	Human-readable error message.
`errorCode`	`AudioProErrorCode \| number`	Numeric code identifying the error category (see below).
`recoverable`	`boolean`	`true` if the player may still be usable and could retry automatically.
`cause`	`string` (optional)	Optional underlying exception message from the native layer.
`index`	`number` (optional)	Queue index of the track that caused the error, if known.

`AudioProErrorCode` Reference

Error codes are grouped by category so you can apply broad recovery logic without matching every individual code.

Unknown

Code	Name	Notes
`0`	`UNKNOWN`	Catch-all for unmapped errors.

Network Errors (1xxx) — typically recoverable

Code	Name	Notes
`1001`	`NETWORK_TIMEOUT`	Request timed out.
`1002`	`NETWORK_FAILED`	General network failure.
`1003`	`TIMEOUT`	Generic timeout.
`1004`	`IO_UNSPECIFIED`	Unspecified I/O error.
`1005`	`INVALID_CONTENT_TYPE`	Server returned an unexpected MIME type.

Decoding Errors (2xxx) — typically unrecoverable

Code	Name	Notes
`2001`	`DECODING_FAILED`	Audio decoding failed.
`2002`	`AUDIO_TRACK_INIT_FAILED`	Failed to initialise the audio track.
`2003`	`DECODER_INIT_FAILED`	Could not initialise a decoder.
`2004`	`DECODER_QUERY_FAILED`	Decoder capability query failed.
`2005`	`FORMAT_UNSUPPORTED`	Audio format is not supported.
`2006`	`FORMAT_EXCEEDS_CAPABILITIES`	Format exists but exceeds device capabilities.

DRM Errors (3xxx) — typically unrecoverable

Code	Name	Notes
`3001`	`DRM_UNSPECIFIED`	Unspecified DRM error.
`3002`	`DRM_SCHEME_UNSUPPORTED`	DRM scheme not supported on device.
`3003`	`DRM_PROVISIONING_FAILED`	Device provisioning failed.
`3004`	`DRM_LICENSE_ACQUISITION_FAILED`	Could not acquire a DRM licence.
`3005`	`DRM_LICENSE_EXPIRED`	DRM licence has expired.

Content Errors (4xxx)

Code	Name	Notes
`4001`	`CONTENT_NOT_FOUND`	Resource returned 404 or equivalent.
`4002`	`BAD_HTTP_STATUS`	Server returned an unexpected HTTP status code.
`4003`	`CONTAINER_MALFORMED`	Audio container is corrupt or malformed.
`4004`	`MANIFEST_MALFORMED`	HLS/DASH manifest could not be parsed.
`4005`	`BEHIND_LIVE_WINDOW`	Seek position falls behind the live window edge.

Reading Error State

Reactively with `useAudioPro()`

The error field in useAudioPro() is updated whenever a PLAYBACK_ERROR event fires and cleared automatically when the player transitions out of the error state.

import { useAudioPro } from 'react-native-audio-pro';

function ErrorBanner() {
  const { error } = useAudioPro();

  if (!error) return null;

  return (
    <View>
      <Text>Error: {error.error}</Text>
      <Text>Code: {error.errorCode}</Text>
      <Text>{error.recoverable ? 'Recoverable' : 'Unrecoverable'}</Text>
    </View>
  );
}

Imperatively with `AudioPro.getError()`

Call AudioPro.getError() anywhere outside of a React component — in event handlers, service classes, or background tasks.

const currentError = AudioPro.getError();

if (currentError) {
  console.log('Last error:', currentError.error, '| code:', currentError.errorCode);
}

Error state clears automatically when the player transitions out of the ERROR state — for example when you call play() after recovery. You do not need to clear it manually.

Complete Error-Handling Component

The example below renders an error banner with the error message, code, and recoverability label. For recoverable errors it also offers a retry button.

import React, { useCallback } from 'react';
import { Button, Text, View } from 'react-native';
import {
  AudioPro,
  AudioProErrorCode,
  AudioProState,
  useAudioPro,
} from 'react-native-audio-pro';

export function PlaybackErrorBanner() {
  const { error, state } = useAudioPro();

  const handleRetry = useCallback(() => {
    // Check current state before forcing a retry — the player may already
    // be recovering on its own
    const currentState = AudioPro.getPlaybackState();

    if (
      currentState !== AudioProState.PLAYING &&
      currentState !== AudioProState.LOADING
    ) {
      const activeIndex = AudioPro.getCurrentMediaItemIndex();

      if (activeIndex >= 0) {
        AudioPro.seekToMediaItem(activeIndex);
        setTimeout(() => AudioPro.play(), 100);
      } else {
        AudioPro.play();
      }
    }
  }, []);

  if (!error) return null;

  const isNetworkError =
    typeof error.errorCode === 'number' &&
    error.errorCode >= 1000 &&
    error.errorCode < 2000;

  return (
    <View>
      <Text>
        {error.recoverable ? 'Recoverable error' : 'Unrecoverable error'}
      </Text>

      <Text>{error.error}</Text>

      <Text>
        Code: {error.errorCode ?? AudioProErrorCode.UNKNOWN}
        {isNetworkError ? ' (network)' : ''}
      </Text>

      {error.cause ? <Text>Cause: {error.cause}</Text> : null}

      {error.recoverable && (
        <Button title="Retry" onPress={handleRetry} />
      )}

      {state === AudioProState.ERROR && (
        <Text>Player stopped. Tap retry to reload.</Text>
      )}
    </View>
  );
}

recoverable: true means the native player considers itself still usable and may already be retrying automatically. Call AudioPro.getPlaybackState() before forcing a manual retry — if the state is already PLAYING or LOADING, skip the retry to avoid interrupting the ongoing recovery attempt.

Getting Started

Core Concepts

Guides

Playback Error Handling in React Native Audio Pro SDK

Two Error Paths

1. `PLAYBACK_ERROR` Event

2. `STATE_CHANGED` with `state: AudioProState.ERROR`

`AudioProPlaybackErrorPayload`

`AudioProErrorCode` Reference

Unknown

Network Errors (1xxx) — typically recoverable

Decoding Errors (2xxx) — typically unrecoverable

DRM Errors (3xxx) — typically unrecoverable

Content Errors (4xxx)

Reading Error State

Reactively with `useAudioPro()`

Imperatively with `AudioPro.getError()`

Complete Error-Handling Component

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Guides

Documentation Index

​Two Error Paths

​1. PLAYBACK_ERROR Event

​2. STATE_CHANGED with state: AudioProState.ERROR

​AudioProPlaybackErrorPayload

​AudioProErrorCode Reference

​Unknown

​Network Errors (1xxx) — typically recoverable

​Decoding Errors (2xxx) — typically unrecoverable

​DRM Errors (3xxx) — typically unrecoverable

​Content Errors (4xxx)

​Reading Error State

​Reactively with useAudioPro()

​Imperatively with AudioPro.getError()

​Complete Error-Handling Component

Build docs developers (and LLMs) love

Two Error Paths

1. `PLAYBACK_ERROR` Event

2. `STATE_CHANGED` with `state: AudioProState.ERROR`

`AudioProPlaybackErrorPayload`

`AudioProErrorCode` Reference

Unknown

Network Errors (1xxx) — typically recoverable

Decoding Errors (2xxx) — typically unrecoverable

DRM Errors (3xxx) — typically unrecoverable

Content Errors (4xxx)

Reading Error State

Reactively with `useAudioPro()`

Imperatively with `AudioPro.getError()`

Complete Error-Handling Component