Errors

When a video can't play, the viewer gets a clear message in their own language instead of an endless spinner, and your code gets a stable code to act on. Try each failure below, and watch what onError receives.

"use client";import { useMemo, useState } from "react";import { definePlugin } from "react-video-kit/core";import { VideoKitError } from "react-video-kit/errors";import { VideoPlayer } from "react-video-kit/player";const POSTER = "/media/poster.jpg";// Stands in for a lost connection, which is hard to arrange on purpose.const lostConnection = definePlugin("lostConnection", () => ({  gates: {    load(request, next) {      if (request.source.src !== "/media/connection.mp4") return next(request);      throw new VideoKitError("media-network", "A network error stopped the download.", { retryable: true });    },  },}));const FAILURES = [  { label: "Damaged file", src: "/media/broken.mp4" },  { label: "Lost connection", src: "/media/connection.mp4" },  { label: "Nothing can play it", src: { src: "/media/unknown.mxf", type: "application/mxf" } },];export default function Errors() {  const [failure, setFailure] = useState(0);  const [log, setLog] = useState<string[]>([]);  const plugins = useMemo(() => [lostConnection()], []);  const current = FAILURES[failure] as (typeof FAILURES)[number];  return (    <div className="flex flex-col gap-3">      <div className="flex flex-wrap gap-2">        {FAILURES.map(({ label }, index) => (          <button key={label} type="button" aria-pressed={index === failure} onClick={() => setFailure(index)}>            {label}          </button>        ))}      </div>      <VideoPlayer        src={current.src}        poster={POSTER}        plugins={plugins}        load="visible"        onError={({ code, fatal, retryable }) =>          setLog((lines) => [JSON.stringify({ code, fatal, retryable }), ...lines].slice(0, 5))        }      />      <ol aria-label="What onError received" className="flex min-h-24 flex-col gap-1 font-mono text-xs break-all text-current">        {log.map((line, index) => (          <li key={index}>{line}</li>        ))}      </ol>    </div>  );}

The error object

Every error has the same shape, on media.error and in onError:

interface MediaErrorInfo {  code: VideoErrorCode; // "media-decode"  message: string; // The browser's or engine's own words, for logs  fatal: boolean; // Did this stop playback?  retryable?: boolean; // Could trying again work?  nativeCode?: number | string; // The browser's or engine's own code  cause?: unknown; // The original error or event  source?: SourceObject; // The source that failed}

code stays the same between versions, so it's safe to compare against. message isn't: it's whatever the browser or engine said, in English or not, and it can change. Log it, but don't show it to viewers, and don't match on it.

What the viewer sees

VideoPlayer and ErrorOverlay show a title and a line of explanation, translated by the i18n plugin, with the code underneath so that viewers can quote it to support. Try again only appears when trying again could work.

To change the words for a code, pass errorMessages to VideoPlayer, or messages to ErrorOverlay:

<VideoPlayer  src="/video.mp4"  errorMessages={{    "drm-denied": { title: "Subscribe to watch", detail: "Plans start at $5 a month." },  }}/>

Handling errors

Log them

onError on VideoPlayer or Video.Root hears every error, fatal or not. It's the right place to tell an error service.

<VideoPlayer  src="/video.mp4"  onError={(error) => {    Sentry.captureMessage(`Video: ${error.code}`, {      level: error.fatal ? "error" : "warning",      extra: { message: error.message, nativeCode: error.nativeCode, source: error.source?.src },    });  }}/>

Outside React, or for a player you made yourself, use player.onError, which returns a function that stops listening:

const stop = player.onError((error) => console.warn(error.code, error.message));

With the recovery plugin, onError hears each failed try, not only the last. A failed source that a fallback took over from arrives with fatal: false, because the viewer's video kept going.

Sources can hold signed URLs, so check what source and message contain before sending them to another service.

Show your own message

Read media.error to replace the overlay. Check fatal, because the latest error may be one that playback carried on through.

"use client";import * as Video from "react-video-kit";function ErrorMessage() {  const error = Video.useVideoState((media) => (media.error?.fatal ? media.error : null));  return error ? (    <div role="alert" className="absolute inset-0 flex flex-col items-center justify-center gap-1 bg-black/60 p-6 text-center text-white">      <p className="text-sm font-medium">Sorry, this video didn&apos;t load.</p>      <p className="max-w-md text-xs opacity-70">Quote {error.code} if you contact support.</p>    </div>  ) : null;}export default function FailedSource() {  return (    <Video.Root src="/media/broken.mp4" load="visible">      <Video.Media width={640} height={360} poster="/media/poster.jpg" />      <ErrorMessage />    </Video.Root>  );}

function ErrorMessage() {  const error = useVideoState((media) => (media.error?.fatal ? media.error : null));  const { reload } = useCommands();  if (!error) return null;  return (    <div role="alert">      <p>Sorry, this video didn't load. ({error.code})</p>      {error.retryable === false ? null : <button onClick={() => reload()}>Try again</button>}    </div>  );}

reload picks up where the failure happened, and plays again if the viewer was watching.

Check a code

react-video-kit/errors has the table below as data, for code that needs to know about a code it hasn't seen yet:

import { ERROR_CODES, isRetryable } from "react-video-kit/errors";ERROR_CODES["media-network"]; // { fatal: true, retryable: true }isRetryable("drm-denied"); // falseisRetryable(error); // Uses error.retryable first, then the code

It's a separate entry, so a player that doesn't import it doesn't carry the table.

Report errors from a plugin

Report a failure with context.error, using your own code, and it behaves like any other: a fatal one moves to the next fallback or stops playback, and onError hears it.

context.error({ code: "my-plugin-expired", message: "The session ended.", fatal: true, retryable: false });

Providers do the same through sink.error. From a load gate or a provider's load, throw a VideoKitError to choose the code:

import { VideoKitError } from "react-video-kit/errors";throw new VideoKitError("my-token-failed", "The token server returned 500.", { retryable: true });

Anything else thrown there is reported as source-load-failed. Leave retryable out if you can't say: recovery won't retry the error, and the overlay still offers Try again.

Fatal and retried

• Fatal means playback stopped. If the source was one of several, and nothing has played yet, the player tries the next one first.
• Retried means retryable is true. The recovery plugin retries it by itself, and the overlay offers Try again once retries run out. Without that plugin, the overlay offers it straight away.

The browser

Reported by the browser's own media element, with its MediaError number as nativeCode.

Sources and playing

HLS

Reported when hls.js gives up. It retries downloads and recovers from media errors on its own first, and what it recovers from isn't reported. nativeCode is its details, such as fragLoadError, and cause is its whole error, where cause.response.code has any HTTP status.

DASH

Reported when dash.js gives up. nativeCode is its error number. Errors from the media element itself use the media- codes.

DRM

The same codes come from the DRM plugin in native playback, and from hls.js and dash.js.

Ads

The ads plugin fails open, so none of these stop the video. They also reach the plugin's own onError.

Casting

The viewer stays on this device when casting fails, so none of these stop the video. nativeCode has the Cast SDK's own code.

Mistakes in code

These are thrown as a VideoKitError while you're building, rather than reported to viewers. Each has a code, and a message saying how to fix it.

API

(error: MediaErrorInfo | VideoErrorCode) => boolean

readonly DeveloperErrorCode[]

Readonly<Record<KnownVideoErrorCode, ErrorCodeInfo>>

typeof VideoKitError

DeveloperErrorCode

KnownVideoErrorCode

VideoErrorCode