remotion-dev/remotion · error · MediaPlaybackError

The browser threw an error while playing the video ${src}: C

Error message

The browser threw an error while playing the video ${src}: Code ${current.error.code} - ${current?.error?.message}. See https://remotion.dev/docs/media-playback-error for help. Pass an onError() prop to handle the error.

What it means

When the underlying `<video>` element emits an `error` event in the preview (`<Video>`) path and no `onError` prop is supplied, Remotion re-throws a `MediaPlaybackError` containing the browser's error code and message plus a documentation link. This is the detailed variant of the error (fires when `current.error` is populated).

Source

Thrown at packages/core/src/video/VideoForPreview.tsx:265

			return;
		}

		const errorHandler = () => {
			if (current.error) {
				// eslint-disable-next-line no-console
				console.error('Error occurred in video', current?.error);

				// If user is handling the error, we don't cause an unhandled exception
				if (onError) {
					const err = new MediaPlaybackError({
						message: `Code ${current.error.code}: ${current.error.message}`,
						src: src as string,
					});
					onError(err);
					return;
				}

				throw new MediaPlaybackError({
					message: `The browser threw an error while playing the video ${src}: Code ${current.error.code} - ${current?.error?.message}. See https://remotion.dev/docs/media-playback-error for help. Pass an onError() prop to handle the error.`,
					src: src as string,
				});
			} else {
				// If user is handling the error, we don't cause an unhandled exception
				if (onError) {
					const err = new MediaPlaybackError({
						message: `The browser threw an error while playing the video ${src}`,
						src: src as string,
					});
					onError(err);
					return;
				}

				throw new MediaPlaybackError({
					message: 'The browser threw an error while playing the video',
					src: src as string,
				});

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Add an `onError` prop to `<Video>` to handle the failure gracefully.
Re-encode the asset to a faststart H.264 MP4 (moov atom at the front).
Verify the URL and CORS headers from the playback environment.
Match codec to the player runtime (e.g. WebM/VP9 for Chromium-only).

Example fix

// before
<Video src={url} />
// after
<Video src={url} onError={(err) => console.error('video error', err)} />

Defensive patterns

Strategy: try-catch

Validate before calling

// Validate codec/URL before playback
const canPlay = document.createElement('video').canPlayType('video/mp4');
if (canPlay === '') throw new Error('Codec not supported');

Type guard

const isPlayableCodec = (mime: string): boolean => ['probably','maybe'].includes(document.createElement('video').canPlayType(mime));

Try / catch

<Video
  src={url}
  onError={(err) => {
    // log, fallback, or surface to UI
    console.error('video playback error', err);
  }}
/>

Prevention

Always pass `onError` to `<Video>` in production apps.
Use faststart H.264 MP4 for broad browser support.
Verify CORS headers (`Access-Control-Allow-Origin`) for remote assets.

When it happens

Trigger: The HTML5 video element fails to load or decode `src` during preview/Studio playback and no `onError` handler is provided on `<Video>`.

Common situations: Unsupported codec (e.g. MOV in Chrome), CORS rejection, broken URL, network drop, or a transcoded asset whose moov atom is at the end (non-faststart MP4).

Related errors

AI-assisted analysis of remotion-dev/remotion@78fe4bb3fd (2026-08-12). Data as JSON: /api/errors/50214b562ebddaff. Report an issue: GitHub.