remotion-dev/remotion · error · TypeError

The `<Html5Video>` tag requires a string for `src`, but got

Error message

The `<Html5Video>` tag requires a string for `src`, but got ${JSON.stringify(props.src)} instead.

What it means

TypeError thrown by Html5Video when `props.src` is not a string. The component requires `src` to be a plain string URL (a staticFile path or absolute URL). The error message echoes the actual value via JSON.stringify so the developer can see exactly what was passed. This guard runs after the CSR and string-ref checks.

Source

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

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

	const durationFetched =
		durations[getAbsoluteSrc(preloadedSrc)] ??
		durations[getAbsoluteSrc(props.src)];

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Ensure src is a string: use `staticFile('my.mp4')` for assets in public/, or an absolute URL string.
If importing a module, access the string path: `import vid from './vid.mp4'; <Html5Video src={vid} />` only if the bundler resolves it to a string URL; otherwise use staticFile.
Add a runtime check before render: `if (typeof src !== 'string') throw new Error('src must be string');`.

Example fix

// before (module object passed by mistake)
import vid from './video.mp4';
<Html5Video src={vid} />

// after
import {staticFile} from 'remotion';
<Html5Video src={staticFile('video.mp4')} />

Defensive patterns

Strategy: type-guard

Validate before calling

const srcIsString = typeof props.src === 'string';
if (!srcIsString) throw new Error('src must be a string URL');

Type guard

const isStringSrc = (src: unknown): src is string => typeof src === 'string';

Prevention

Always pass `staticFile('name.mp4')` or a literal URL string to src.
Type the prop as `src: string` in your own wrappers.
Avoid passing imported module objects or Blob/File directly.

When it happens

Trigger: Passing a non-string to Html5Video's `src` prop: an object (e.g. an imported module's default), undefined, a number, a React element, or a Blob. Typical when a developer passes `src={importedVideo}` where the import is an object, or forgets the src entirely.

Common situations: Importing a video as an ES module and passing the module object instead of its `.src`/`.default`; conditional rendering that leaves src undefined for some frames; passing a Blob/File object from a file input directly as src.

Related errors

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