remotion-dev/remotion · error · TypeError

staticFile() does not support remote URLs - got "${path}". I

Error message

staticFile() does not support remote URLs - got "${path}". Instead, pass the URL without wrapping it in staticFile(). See: https://remotion.dev/docs/staticfile-remote-urls

What it means

staticFile() only resolves files in your project's public/ folder. It cannot fetch remote URLs because rendering happens offline against local assets, and bundling would not include remote content. This guard detects `http://` or `https://` URLs and points you to the dedicated remote-URL handling pattern.

Source

Thrown at packages/core/src/static-file.ts:101

	const merged = encodedArray.join('/');
	return merged;
};

/*
 * @description Reference a file from the public/ folder. If the file does not appear in the autocomplete, type the path manually.
 * @see [Documentation](https://www.remotion.dev/docs/staticfile)
 */
export const staticFile = (path: string) => {
	if (path === null) {
		throw new TypeError('null was passed to staticFile()');
	}

	if (typeof path === 'undefined') {
		throw new TypeError('undefined was passed to staticFile()');
	}

	if (path.startsWith('http://') || path.startsWith('https://')) {
		throw new TypeError(
			`staticFile() does not support remote URLs - got "${path}". Instead, pass the URL without wrapping it in staticFile(). See: https://remotion.dev/docs/staticfile-remote-urls`,
		);
	}

	if (path.startsWith('..') || path.startsWith('./')) {
		throw new TypeError(
			`staticFile() does not support relative paths - got "${path}". Instead, pass the name of a file that is inside the public/ folder. See: https://remotion.dev/docs/staticfile-relative-paths`,
		);
	}

	if (
		path.startsWith('/Users') ||
		path.startsWith('/home') ||
		path.startsWith('/tmp') ||
		path.startsWith('/etc') ||
		path.startsWith('/opt') ||
		path.startsWith('/var') ||
		path.startsWith('C:') ||

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Pass the remote URL directly to the component without staticFile(): `<Img src={remoteUrl} />`.
2. Branch in your component: `const src = isRemote ? url : staticFile(url);`.
3. Use the appropriate remote-URL APIs described at https://remotion.dev/docs/staticfile-remote-urls.

Example fix

// before
<Img src={staticFile(avatarUrl)} />

// after
<Img src={avatarUrl.startsWith('http') ? avatarUrl : staticFile(avatarUrl)} />

const resolveSrc = (src: string) =>
  src.startsWith('http://') || src.startsWith('https://')
    ? src
    : staticFile(src);

const isRemoteUrl = (v: string) =>
  v.startsWith('http://') || v.startsWith('https://');

When it happens

Trigger: Calling `staticFile('https://example.com/video.mp4')` or `staticFile('http://cdn.example.com/audio.mp3')`, often by passing a prop that already holds a remote URL into a component that wraps it with staticFile().

Common situations: Generic media components that wrap every src in staticFile() being reused with remote URLs; migrating from local to remote assets without updating the consumer.

Related errors

• The value "${path}" is already prefixed with the static base
• null was passed to staticFile()
• undefined was passed to staticFile()
• staticFile() does not support relative paths - got "${path}"
• staticFile() does not support absolute paths - got "${path}"

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