remotion-dev/remotion · error · Error

Loading Google Fonts without specifying weights and subsets

Error message

Loading Google Fonts without specifying weights and subsets is not supported in Remotion v5. Please specify the weights and subsets you need.

What it means

Thrown by @remotion/google-fonts `loadFonts` when running under Remotion v5 breaking-changes mode and the caller did not specify both `weights` and `subsets` as non-empty arrays. Remotion v5 removed the implicit 'load everything' behavior of v4 to avoid downloading unused font files; you must now declare exactly which weights and subsets you need.

Source

Thrown at packages/google-fonts/src/base.ts:95

		? V5Options
		: V4Options,
): {
	fontFamily: FontInfo['fontFamily'];
	fonts: FontInfo['fonts'];
	unicodeRanges: FontInfo['unicodeRanges'];
	waitUntilDone: () => Promise<undefined>;
} => {
	const weightsAndSubsetsAreSpecified =
		Array.isArray(options?.weights) &&
		Array.isArray(options?.subsets) &&
		options.weights.length > 0 &&
		options.subsets.length > 0;

	if (
		NoReactInternals.ENABLE_V5_BREAKING_CHANGES &&
		!weightsAndSubsetsAreSpecified
	) {
		throw new Error(
			'Loading Google Fonts without specifying weights and subsets is not supported in Remotion v5. Please specify the weights and subsets you need.',
		);
	}

	const promises: Promise<void>[] = [];
	const styles = style ? [style] : Object.keys(meta.fonts);

	let fontsLoaded = 0;

	for (const style of styles) {
		// Don't load fonts on server
		if (typeof FontFace === 'undefined') {
			continue;
		}

		if (!meta.fonts[style]) {
			throw new Error(
				`The font ${meta.fontFamily} does not have a style ${style}`,

View on GitHub (pinned to 78fe4bb3fd)

Solutions

Add explicit `weights` and `subsets` arrays to the options, e.g. `loadFonts(meta, 'normal', {weights: ['400','700'], subsets: ['latin']})`.
Consult the font's metadata (or the @remotion/google-fonts docs page for that family) to find the available weights and subsets.
If you cannot move to v5 yet, keep the v4 behavior by ensuring `ENABLE_V5_BREAKING_CHANGES` is not enabled (but migrating is recommended).

Example fix

// before
const {fontFamily} = loadFonts(meta, 'normal', {});

// after
const {fontFamily} = loadFonts(meta, 'normal', {
  weights: ['400', '700'],
  subsets: ['latin'],
});

Defensive patterns

Strategy: validation

Validate before calling

function assertFontOptions(options: {weights?: string[]; subsets?: string[]}) {
  if (!options.weights?.length || !options.subsets?.length) {
    throw new Error('In Remotion v5 you must pass non-empty weights and subsets arrays.');
  }
}

assertFontOptions(opts);
loadFonts(meta, 'normal', opts);

Type guard

function hasV5FontOptions(options: unknown): options is {weights: string[]; subsets: string[]} {
  return (
    !!options &&
    Array.isArray((options as any).weights) && (options as any).weights.length > 0 &&
    Array.isArray((options as any).subsets) && (options as any).subsets.length > 0
  );
}

Prevention

After upgrading to Remotion v5, audit every loadFonts/getFont call and add weights + subsets.
Copy the exact weights and subsets from the font's @remotion/google-fonts docs page.
Write a unit test that loads each font you use with explicit weights/subsets to catch regressions.

When it happens

Trigger: Calling `loadFonts(meta, 'normal', {})`, `loadFonts(meta, 'normal', {weights: ['400']})` (subsets missing), or any v4-style call that omits both arrays. The guard checks `ENABLE_V5_BREAKING_CHANGES` plus that both arrays exist and have length > 0.

Common situations: Upgrading a project from Remotion v4 to v5 without updating existing `loadFonts`/`getFont` calls; copy-pasting a v4 example; the auto-generated font loader for a font family that was created before v5.

Related errors

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