remotion-dev/remotion · error · TypeError

Do not include the public/ prefix when using staticFile() -

Error message

Do not include the public/ prefix when using staticFile() - got "${path}". See: https://remotion.dev/docs/staticfile-relative-paths

What it means

staticFile() already resolves paths against the public/ folder, so including the literal `public/` prefix in the argument produces a doubled path (`/public/public/foo`). This guard rejects paths starting with `public/` and asks you to drop the prefix.

Source

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

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

	if (path.startsWith('public/')) {
		throw new TypeError(
			`Do not include the public/ prefix when using staticFile() - got "${path}". See: https://remotion.dev/docs/staticfile-relative-paths`,
		);
	}

	const includesHex = includesHexOfUnsafeChar(path);
	if (includesHex.containsHex) {
		warnOnce(
			`WARNING: You seem to pass an already encoded path (path contains ${includesHex.hexCode}). Since Remotion 4.0, the encoding is done by staticFile() itself. You may want to remove a encodeURIComponent() wrapping.`,
		);
	}

	if (typeof window !== 'undefined') {
		// This lookup is primarily used by Browser Studio, where virtual assets
		// have blob: URLs. Regular Studio sources are already encoded using the
		// same per-path-segment encoding as the fallback below.
		const matchingStaticFile = window.remotion_staticFiles?.find(
			(file) => file.name === trimLeadingSlash(path),
		);

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Drop the `public/` prefix: `staticFile('foo.png')`.
2. If you build paths programmatically, strip a leading `public/` with `path.replace(/^public\//, '')`.
3. Treat the argument to staticFile() as relative to public/, not to the project root.

Example fix

// before
const src = staticFile('public/soundtrack.mp3');

// after
const src = staticFile('soundtrack.mp3');

const safeStaticFile = (p: string) =>
  staticFile(p.replace(/^public\//, ''));

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

When it happens

Trigger: Calling `staticFile('public/foo.png')` or `staticFile('public/videos/intro.mp4')`, usually because the developer thinks of the path from the project root.

Common situations: Autocompleting from the project root in an editor; copying paths from file explorers that include the public/ folder name; onboarding from frameworks where you do reference the folder explicitly.

Related errors

• staticFile() does not support relative paths - got "${path}"
• staticFile() does not support absolute paths - got "${path}"
• 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/9da565d20323213d. Report an issue: GitHub.