remotion-dev/remotion · error · TypeError

Expected a URL string but received ${url === undefined ? 'un

Error message

Expected a URL string but received ${url === undefined ? 'undefined' : typeof url}. Make sure to pass a "url" field in the options object of loadFont().

What it means

The `getFontFormat` helper derives a CSS font format from a URL's file extension. It expects a string argument and throws a TypeError if the value is not a string (e.g., undefined, number, or object). This is called internally by `loadFont` when no explicit `format` is provided, so the error surfaces the missing or mistyped `url` field.

Source

Thrown at packages/fonts/src/get-font-format.ts:5

export type FontFormat = 'woff2' | 'woff' | 'opentype' | 'truetype';

export const getFontFormat = (url: string): FontFormat => {
	if (typeof url !== 'string') {
		throw new TypeError(
			`Expected a URL string but received ${url === undefined ? 'undefined' : typeof url}. Make sure to pass a "url" field in the options object of loadFont().`,
		);
	}

	const ext = url.split('.').pop()?.toLowerCase();
	switch (ext) {
		case 'woff2':
			return 'woff2';
		case 'woff':
			return 'woff';
		case 'otf':
			return 'opentype';
		case 'ttf':
			return 'truetype';
		default:
			throw new Error(
				`Could not automatically derive font format from extension: ${ext}. Pass the "format" parameter explicitly.`,
			);

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Ensure the `url` field in `loadFont` options is a non-empty string.
If calling `getFontFormat` directly, pass a valid URL string.
Check for typos in the options key name (e.g., `src` instead of `url`).

Example fix

// before
loadFont({ family: 'MyFont' }); // missing url

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

Defensive patterns

Strategy: type-guard

Validate before calling

if (typeof url !== 'string' || url.length === 0) {
  throw new TypeError('A non-empty url string is required');
}
const format = getFontFormat(url);

Type guard

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

Prevention

Always include a string url field in loadFont options.
Use TypeScript to enforce the LoadFontOptions shape at compile time.
Check for undefined url before calling loadFont when building options dynamically.

When it happens

Trigger: Calling `getFontFormat()` directly with a non-string, or calling `loadFont()` with an options object where `url` is missing or not a string and no `format` is specified. The ternary in the message distinguishes `undefined` from other types for clearer debugging.

Common situations: Passing a font configuration object where the `url` key was misspelled or omitted, deserializing font config from JSON where the URL became null, or calling `loadFont({family: 'MyFont'})` without a URL.

Related errors

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