remotion-dev/remotion · error · TypeError

undefined was passed to staticFile()

Error message

undefined was passed to staticFile()

What it means

staticFile() expects a string path to a file in the public/ folder. This guard catches an `undefined` argument, which is the most common mistake when a variable, prop, or config field is not set. The runtime guard exists because undefined reaches the call site through optional fields, missing imports, or untyped data even though the parameter is typed as string.

Source

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

	const encodedArray = splitBySlash.map((element) => {
		return encodeURIComponent(element);
	});
	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') ||

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Provide a default string, e.g. `staticFile(props.src ?? 'fallback.png')`.
2. Add a runtime check that the path is a non-empty string before calling staticFile().
3. Fix the upstream source of the undefined value (missing import, wrong key, unset field).

Example fix

// before
const src = staticFile(props.backgroundUrl);

// after
if (!props.backgroundUrl) {
  throw new Error('backgroundUrl is required');
}
const src = staticFile(props.backgroundUrl);

const resolveAsset = (path: string | undefined, fallback?: string) => {
  if (path === undefined) {
    if (fallback) return staticFile(fallback);
    throw new Error('asset path is undefined');
  }
  return staticFile(path);
};

const isDefinedString = (v: unknown): v is string =>
  typeof v === 'string';

When it happens

Trigger: Calling `staticFile(undefined)`, passing an object property that was never set (e.g. `staticFile(props.src)` when `src` is optional and omitted), or referencing a missing named export.

Common situations: Optional props that default to undefined; destructuring with a typo in the key name; data-driven renders where the asset path field is absent in some records.

Related errors

• null was passed to staticFile()
• input can not be undefined
• inputRange can not be undefined
• outputRange can not be undefined
• input can not be undefined

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