Error handling

Available in Classic and VPC

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

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.

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.

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)
        },
      }}
    />
  );
}

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

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: