remotion-dev/remotion · error · TypeError

staticFile() does not support relative paths - got "${path}"

Error message

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

What it means

staticFile() resolves paths relative to the public/ folder root, so it does not accept `./` or `../` relative prefixes. Those would resolve against the working directory at runtime, which is not well-defined inside Remotion's bundler and would break in the Studio and during rendering.

Source

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

 * @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:') ||
		path.startsWith('D:') ||
		path.startsWith('E:')
	) {
		throw new TypeError(
			`staticFile() does not support absolute paths - got "${path}". Instead, pass the name of a file that is inside the public/ folder. See: https://remotion.dev/docs/staticfile-relative-paths`,
		);

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Pass only the file name relative to public/, e.g. `staticFile('foo.png')` or `staticFile('shared/bar.mp3')`.
2. Move the asset into the public/ folder if it currently sits outside it.
3. Strip leading `./` and `../` and any `public/` prefix before calling staticFile().

Example fix

// before
const src = staticFile('../assets/intro.mp4');

// after (move assets/intro.mp4 to public/intro.mp4 first)
const src = staticFile('intro.mp4');

const safeStaticFile = (p: string) => {
  const stripped = p.replace(/^(\.\.\/|\.\/)+/, '');
  return staticFile(stripped);
};

const isBarePublicPath = (p: string) =>
  !p.startsWith('./') && !p.startsWith('../') && !p.startsWith('public/');

When it happens

Trigger: Calling `staticFile('./foo.png')` or `staticFile('../shared/bar.mp3')`, often because the developer copy-pasted a relative import path.

Common situations: Treating staticFile() like a Node import; sharing path constants between ES imports and staticFile() calls; refactoring a file layout and reusing relative paths.

Related errors

• staticFile() does not support absolute paths - got "${path}"
• Do not include the public/ prefix when using staticFile() -
• The value "${path}" is already prefixed with the static base
• null was passed to staticFile()
• undefined was passed to staticFile()

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