remotion-dev/remotion · error · TypeError

loadFont() requires an object as its argument, but received

Error message

loadFont() requires an object as its argument, but received ${typeof options === 'string' ? `"${options}"` : typeof options}. If you want to load a Google Font, use the @remotion/google-fonts package instead. See: https://www.remotion.dev/docs/google-fonts/load-font

What it means

The `loadFont` function requires an options object as its sole argument. If called with a string (e.g., just a URL), null, or any non-object value, it throws a TypeError directing you to use the correct options shape or `@remotion/google-fonts` for Google Fonts. This is the first validation check in the function.

Source

Thrown at packages/fonts/src/load-font.ts:23

export type LoadFontOptions = {
	family: string;
	url: string;
	ascentOverride?: string;
	descentOverride?: string;
	display?: 'auto' | 'block' | 'fallback' | 'optional' | 'swap';
	featureSettings?: string;
	lineGapOverride?: string;
	stretch?: string;
	style?: string;
	unicodeRange?: string;
	variant?: string;
	weight?: string;
	format?: FontFormat;
};

export const loadFont = async (options: LoadFontOptions): Promise<void> => {
	if (typeof options !== 'object' || options === null) {
		throw new TypeError(
			`loadFont() requires an object as its argument, but received ${typeof options === 'string' ? `"${options}"` : typeof options}. If you want to load a Google Font, use the @remotion/google-fonts package instead. See: https://www.remotion.dev/docs/google-fonts/load-font`,
		);
	}

	const {
		family,
		url,
		ascentOverride,
		descentOverride,
		display,
		featureSettings,
		lineGapOverride,
		stretch,
		style,
		unicodeRange,
		weight,
		format,
		variant,

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Pass an options object with at least `family` and `url`: `loadFont({family: 'MyFont', url: '...'})`.
For Google Fonts, use `@remotion/google-fonts` instead of `loadFont`.
Check that the argument is the options object, not a URL string.

Example fix

// before
loadFont('https://example.com/fonts/myfont.woff2');

// after
loadFont({
  family: 'MyFont',
  url: 'https://example.com/fonts/myfont.woff2',
});

Defensive patterns

Strategy: type-guard

Validate before calling

if (typeof options !== 'object' || options === null) {
  throw new TypeError('loadFont requires an options object');
}
loadFont(options);

Type guard

const isLoadFontOptions = (v: unknown): v is Record<string, unknown> =>
  typeof v === 'object' && v !== null;

Prevention

Always call loadFont with an object literal: loadFont({ family, url }).
Use the LoadFontOptions TypeScript type for compile-time checking.
For Google Fonts, use @remotion/google-fonts/loadFont instead.

When it happens

Trigger: Calling `loadFont('https://example.com/font.woff2')` (string instead of object), `loadFont(null)`, `loadFont(undefined)`, or `loadFont(123)`. A common mistake is treating `loadFont` like a simple URL loader.

Common situations: New users expecting `loadFont` to accept a plain URL, migrating from a different font-loading API, or destructuring incorrectly so the wrong variable is passed.

Related errors

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