remotion-dev/remotion · error · Error

string refs are not supported

Error message

string refs are not supported

What it means

Thrown by Html5Video when the `ref` passed to the component is a string. Legacy React string refs (`ref="myVideo"`) are not supported by Remotion's video components, which expect either a callback ref or a RefObject. The check runs on every render after the CSR guard.

Source

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

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

	const preloadedSrc = usePreload(props.src);

	const onDuration = useCallback(
		(src: string, durationInSeconds: number) => {
			setDurations({type: 'got-duration', durationInSeconds, src});
		},
		[setDurations],
	);

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Switch to a RefObject via useRef: `const ref = useRef<HTMLVideoElement>(null); <Html5Video ref={ref} />`.
2. Or use a callback ref: `ref={(el) => { videoEl = el; }}`.

Example fix

// before
<Html5Video ref="myVideo" src={src} />

// after
const videoRef = useRef<HTMLVideoElement>(null);
<Html5Video ref={videoRef} src={src} />

import type {Ref} from 'react';

const isStringRef = (ref: unknown): ref is string => typeof ref === 'string';
if (isStringRef(ref)) throw new Error('use a RefObject or callback ref');

const isSupportedRef = (ref: unknown): boolean =>
  typeof ref !== 'string';

When it happens

Trigger: Passing a string ref to <Html5Video> (or <Video> that forwards to it): `<Html5Video ref="player" />`. This legacy ref API was removed from modern React and Remotion explicitly rejects it.

Common situations: Copying old React tutorials that use string refs; upgrading a codebase from React 15-era patterns; using a ref string by accident when intending a callback or useRef value.

Related errors

• bundle() was called without arguments
• bundle() no longer supports the legacy positional arguments.
• bundle() was called without the `entryPoint` option
• No video stream found in ${file_path}. Is this a video file?
• The codec is not a video codec

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