---
title: "Error handling"
slug: "vpe-react-error-handling"
updated: 2026-09-17T09:22:36Z
published: 2026-09-17T09:22:36Z
canonical: "guide.ncloud-docs.com/vpe-react-error-handling"
stale: true
---

> ## Documentation Index
> Fetch the complete documentation index at: https://guide.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error handling

Available in Classic and VPC

It explains how to detect and handle errors that occur during playback.

              Note

              

You can view the error codes on the Media analytics management page when subscribing the Media Analytics service along with the Video Player Enhancement service.

## Detect error events

The function calling the player can call error codes and messages when detecting the event with the `player.on("error", (err) => {})` code.

              Note

              

The error codes are sent to the error code list provided by the Video Player Enhancement service.

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// Structure of the error event object passed to onEvent:
// {
//   type: "error",
//   state: PlayerStateSnapshot,      // Current player state
//   prevState?: PlayerStateSnapshot,
//   data: {
//     errorCode: string | null,      // example: "E0001", "E0004"
//     errorMessage: string | null,   // Error description
//     errorTitle: string | null,     // Error title
//   }
// }

export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        playlist: [
          {
            file: "https://example.com/myVideo.mp4",
            poster: "https://example.com/myVideoThumb.png",
          },
        ],
      }}
      onEvent={(event) => {
        if (event.type === "error") {
          const { errorCode, errorMessage, errorTitle } = event.data;
          switch (errorCode) {
            case "E0001":
              console.log("E0001 - ACCESS DENIED");
              console.log(errorTitle, errorMessage);
              break;
            case "E0002":
              console.log("E0002 - NOT AUTHORIZED");
              console.log(errorTitle, errorMessage);
              break;
            case "E0003":
              console.log("E0003 - NETWORK ERROR");
              console.log(errorTitle, errorMessage);
              break;
            case "E0004":
              console.log("E0004 - CANNOT PLAY");
              console.log(errorTitle, errorMessage);
              break;
            case "E0005":
              console.log("E0005 - LICENSE IS INVALID");
              console.log(errorTitle, errorMessage);
              break;
            case "E0006":
              console.log("E0006 - LIMIT DENIED");
              console.log(errorTitle, errorMessage);
              break;
            default:
              break;
          }
        }
      }}
    />
  );
}
```

## Retry settings

You can customize the settings of maximum amount of retry attempts and maximum delay time before the player responds to an error.

              Note

              

- Added retry attempts during player initialization: Up to 3 attempts by default, with a 5-second interval
- Added retry attempts for interrupted Live/VOD playback: Up to 3 attempts by default, with a 5-second interval

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        playlist: [
          {
            file: "https://dobdd7vj3864.edge.naverncp.com/hls/47NWZgkwsKFkPIU1tix9Zw__/endpoint/sample/example.mp4.smil/master.m3u8",
            poster: "https://2ardrvaj2252.edge.naverncp.com/endpoint/sample/221027_NAVER_Cloud_intro_Long_ver_01.jpg",
          },
        ],
        retry: {
          maxRetry: 10,   // Maximum amount of retry attempts
          interval: 5000, // Retry delay time (ms)
        },
      }}
    />
  );
}
```

| Option | Type | Default value | Description |
| --- | --- | --- | --- |
| `retry` | Object | - | Retry settings |
| `retry.maxRetry` | Integer | `3` | Maximum amount of retry attempts |
| `retry.interval` | Integer | `5000` | Retry delay time (milliseconds) |

## Error interface override

You can replace the default error interface with your own code. By overriding the error interface, you can implement the error interface through the player overlay while keeping the playback paused at the last playback position.

```
import Hls from "hls.js";
import dashjs from "dashjs";
import { VpePlayer } from "@sgrsoft/vpe-react-sdk";

// Video (MP4)
export function App() {
  return (
    <VpePlayer
      accessKey="YOUR_ACCESS_KEY"
      hls={Hls}
      dashjs={dashjs}
      platform="pub"
      options={{
        playlist: [
          {
            file: "https://CDNdomain/example_video_01.mp4",
            poster: "https://CDNdomain/example_image_01.png",
          },
        ],
        override: {
          error(err) {
            console.log("player error :", err);
            // Customer error interface function implemented
          },
        },
      }}
    />
  );
}
```

## Error interface customizing

              Note

              

- Pass `errorOverride` to VpePlayer props to directly render custom React UI inside the player when an error occurs.
- `override.error` is a callback function set inside options that receives error information and executes external logic (such as logging or separate DOM manipulation).

              Note

              

This works only in the paid tier (`isPaidTier`).

### Type definition

```
errorOverride?: ReactNode | ComponentType<PlayerErrorInfo> | ((info: PlayerErrorInfo) => ReactNode);

type PlayerErrorInfo = {
  errorCode: string | null;
  errorMessage: string | null;
  errorTitle: string | null;
};
```

### 1. Render function (most common)

Render the UI dynamically by receiving error information. Useful when displaying different messages for each error code.

```
<VpePlayer
  accessKey="YOUR_ACCESS_KEY"
  hls={Hls}
  options={{
    playlist: [{ file: "https://CDN_DOMAIN/example.m3u8" }],
  }}
  errorOverride={(info) => (
    <div style={{
      display: "flex",
      width: "100%",
      height: "100%",
      backgroundColor: "#000",
      color: "#fff",
      justifyContent: "center",
      alignItems: "center",
    }}>
      <div>ERROR {info.errorCode}</div>
    </div>
  )}
/>
```

### 2. React component

Define and pass a separate error component. `PlayerErrorInfo` is passed as props.

```
function CustomError({ errorCode, errorMessage }: PlayerErrorInfo) {
  return <div>Error: {errorCode} - {errorMessage}</div>;
}

<VpePlayer
  accessKey="YOUR_ACCESS_KEY"
  hls={Hls}
  options={{
    playlist: [{ file: "https://CDN_DOMAIN/example.m3u8" }],
  }}
  errorOverride={CustomError}
/>
```

### 3. ReactNode (fixed UI)

Display the same fixed UI regardless of the error code.

```
<VpePlayer
  accessKey="YOUR_ACCESS_KEY"
  hls={Hls}
  options={{
    playlist: [{ file: "https://CDN_DOMAIN/example.m3u8" }],
  }}
  errorOverride={<div>Unable to play</div>}
/>
```

## Error code

The following are the error codes provided by Video Player Enhancement service:

| Error code | Error message | Description |
| --- | --- | --- |
| E0001 | ACCESS DENIED | Invalid access. Video playback unavailable due to an invalid option value. |
| E0002 | NOT AUTHORIZED | Not authorized to play this video. Player authentication failed due to an invalid request. |
| E0003 | NETWORK ERROR | Network connection is unstable. Player authentication failed due to a network issue. |
| E0004 | CANNOT PLAY VIDEO | Unable to play video. Video playback failed. |
| E0005 | LICENSE IS INVALID | The license is invalid. Video playback unavailable because the player license has expired. |
| E0006 | LIMIT DENIED | The monthly basic call count has been exceeded. Video playback unavailable because the monthly quota of the free player has been exhausted. |