remotion-dev/remotion · error · Error

<Html5Video> is not supported in @remotion/web-renderer. Use

Error message

<Html5Video> is not supported in @remotion/web-renderer. Use <Video> from @remotion/media instead. See https://remotion.dev/docs/client-side-rendering/limitations

What it means

Thrown at the top of the Html5Video forwarding function when `useRemotionEnvironment().isClientSideRendering` is true. Remotion's client-side-rendering target (@remotion/web-renderer) does not support the native <Html5Video> tag, because CSR plays media live rather than frame-accurately. The message directs users to <Video> from @remotion/media, the CSR-compatible video component. This is part of the v5 package split.

Source

Thrown at packages/core/src/video/html5-video.tsx:52

		endAt,
		trimBefore,
		trimAfter,
		name,
		pauseWhenBuffering,
		_remotionInternalStack,
		_remotionInternalNativeLoopPassed,
		showInTimeline,
		onAutoPlayError,
		onVideoFrame,
		...otherProps
	} = props;
	const {loop, ...propsOtherThanLoop} = props;
	const {fps} = useVideoConfig();
	const environment = useRemotionEnvironment();
	const shouldPauseWhenBuffering = resolveV5Default(pauseWhenBuffering);

	if (environment.isClientSideRendering) {
		throw new Error(
			'<Html5Video> is not supported in @remotion/web-renderer. Use <Video> from @remotion/media instead. See https://remotion.dev/docs/client-side-rendering/limitations',
		);
	}

	const {durations, setDurations} = useContext(DurationsContext);

	if (typeof ref === 'string') {
		throw new Error('string refs are not supported');
	}

	if (typeof props.src !== 'string') {
		throw new TypeError(
			`The \`<Html5Video>\` tag requires a string for \`src\`, but got ${JSON.stringify(
				props.src,
			)} instead.`,
		);
	}

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Replace <Html5Video> with <Video> imported from @remotion/media when targeting client-side rendering.
If you need server-side rendering (Studio, Lambda, CLI render), keep the environment as SSR so Html5Video is permitted.
Audit imports: ensure components that embed video are not loaded into a CSR build of the app.

Example fix

// before (in a client-side-rendering app)
import {Html5Video} from '@remotion/core';

// after
import {Video} from '@remotion/media';

Defensive patterns

Strategy: type-guard

Validate before calling

import {getRemotionEnvironment} from 'remotion';

if (getRemotionEnvironment().isClientSideRendering) {
  // do NOT render <Html5Video> here
}

Type guard

import {getRemotionEnvironment} from 'remotion';

const allowsHtml5Video = (): boolean =>
  !getRemotionEnvironment().isClientSideRendering;

Prevention

In CSR apps, import <Video> from @remotion/media, never Html5Video from @remotion/core.
Gate component choice on getRemotionEnvironment().isClientSideRendering.
Keep CSR and SSR compositions in separate files to avoid accidental cross-imports.

When it happens

Trigger: Mounting <Html5Video> (or <Video> that resolves to Html5Video under the hood) inside a composition that is being rendered or previewed in a client-side-rendering environment where `getRemotionEnvironment().isClientSideRendering === true`. This happens when the app is built with @remotion/web-renderer and the rendering path hits the Html5Video component body.

Common situations: Migrating a server-rendered Remotion app to the v5 @remotion/web-renderer CSR pipeline without swapping the video component; importing Html5Video directly in a composition that runs in the browser-only render target; mixing @remotion/core video primitives with a CSR configuration.

Related errors

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