What causes "The browser threw an error while playing the video" in remotion-dev/remotion?

Always pass an `onError` prop to ` ` to capture these events.

remotion-dev/remotion · error · MediaPlaybackError

The browser threw an error while playing the video

Error message

The browser threw an error while playing the video

What it means

Same handler as the detailed variant, but fires when the `<video>` element emitted an `error` event with no `current.error` object populated and no caller `onError` is supplied. Remotion still throws a `MediaPlaybackError` so the failure surfaces, but without a code/message.

Source

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

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

		current.addEventListener('error', errorHandler, {once: true});
		return () => {
			current.removeEventListener('error', errorHandler);
		};
	}, [onError, src]);

	const currentOnDurationCallback =
		useRef<VideoForPreviewProps['onDuration']>(onDuration);
	currentOnDurationCallback.current = onDuration;

	useEmitVideoFrame({ref: videoRef, onVideoFrame});

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Always pass an `onError` prop to `<Video>` to capture these events.
Ensure autoplay policies are satisfied (`muted`, `playsInline`) so the browser doesn't abort playback.
Avoid rapidly swapping `src`; key the component by URL.

Example fix

// before
<Video src={url} />
// after
<Video src={url} muted playsInline onError={(err) => handleError(err)} />

Defensive patterns

Strategy: try-catch

Validate before calling

// Satisfy autoplay policies
const isAutoplaySafe = (el: HTMLVideoElement) => el.muted && el.playsInline;

Try / catch

<Video
  muted
  playsInline
  src={url}
  onError={(err) => handleVideoError(err)}
/>

Prevention

Always supply `onError` so undocumented error events don't crash playback.
Set `muted` and `playsInline` to avoid autoplay-policy aborts.
Key `<Video>` by `src` to avoid mid-load src swaps.

When it happens

Trigger: The browser fires an error event on the video tag but does not populate `HTMLMediaElement.error` (rare browser quirk or aborted playback), and the caller did not pass `onError`.

Common situations: Browser-specific error quirks, autoplay being blocked before metadata loads, or rapidly switching `src` while a previous load is in flight.

Related errors

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