remotion-dev/remotion · error · TypeError

null was passed to staticFile()

Error message

null was passed to staticFile()

What it means

staticFile() expects a string path to a file in the public/ folder. This guard catches a literal `null` argument. Although TypeScript types the parameter as string, null can reach the call through loose typing, JSON data, or `any`-typed values, so the runtime check exists as a safety net with a clear error message.

Source

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

};

const encodeBySplitting = (path: string): string => {
	const splitBySlash = path.split('/');

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

View on GitHub (pinned to 78fe4bb3fd)

Solutions

1. Ensure the argument is a string; default or fallback before calling staticFile().
2. Filter out null entries when mapping over data, e.g. `paths.filter(Boolean).map(staticFile)`.
3. Tighten the upstream type so null cannot flow into the call.

Example fix

// before
const src = staticFile(assetMap[name]);

// after
const path = assetMap[name];
if (path === null || path === undefined) {
  throw new Error(`missing asset for ${name}`);
}
const src = staticFile(path);

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

const isNonNullString = (v: unknown): v is string =>
  typeof v === 'string' && v.length > 0;

When it happens

Trigger: Calling `staticFile(null)`, passing a variable that is null because a lookup failed (e.g. `staticFile(map[key])` where the key is absent), or feeding `JSON.parse` output that contains null.

Common situations: Optional config objects where a field is null instead of omitted; data-driven renders where an asset key is missing; interop with untyped JavaScript modules.

Related errors

• undefined was passed to staticFile()
• The value "${path}" is already prefixed with the static base
• staticFile() does not support remote URLs - got "${path}". I
• 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/a5be754f4ce4d5be. Report an issue: GitHub.