withastro/astro · warning

Several font families have been registered for the ${bold(fa

Error message

Several font families have been registered for the ${bold(family.cssVariable)} cssVariable but they do not share the same name and provider.

What it means

Astro keys resolved font families by cssVariable + name + provider. When a new family reuses a cssVariable already registered but with a different name or provider, the key differs so the families cannot be merged; Astro warns 'Several font families have been registered for the X cssVariable but they do not share the same name and provider.' The practical effect (stated in the companion warning) is that the last occurrence silently overrides earlier families for that variable.

Source

Thrown at packages/astro/src/assets/fonts/core/get-or-create-font-family-assets.ts:23

	fontFamilyAssetsByUniqueKey,
	logger,
	bold,
	family,
}: {
	fontFamilyAssetsByUniqueKey: FontFamilyAssetsByUniqueKey;
	logger: AstroLogger;
	bold: (input: string) => string;
	family: ResolvedFontFamily;
}) {
	const key = `${family.cssVariable}:${family.name}:${family.provider.name}`;
	let fontAssets = fontFamilyAssetsByUniqueKey.get(key);
	if (!fontAssets) {
		if (
			Array.from(fontFamilyAssetsByUniqueKey.keys()).find((k) =>
				k.startsWith(`${family.cssVariable}:`),
			)
		) {
			logger.warn(
				'assets',
				`Several font families have been registered for the ${bold(family.cssVariable)} cssVariable but they do not share the same name and provider.`,
			);
			logger.warn(
				'assets',
				'These families will not be merged together. The last occurrence will override previous families for this cssVariable. Review your Astro configuration.',
			);
		}
		fontAssets = {
			family,
			fonts: [],
			collectedFontsForMetricsByUniqueKey: new Map(),
			preloads: [],
		};
		fontFamilyAssetsByUniqueKey.set(key, fontAssets);
	}
	return fontAssets;
}

View on GitHub (pinned to 52e6c34790)

Solutions

1. Give each family its own unique cssVariable (or remove the explicit cssVariable so each family gets a unique default)
2. If you intended the families to merge, make name AND provider identical for every entry sharing the variable
3. Review the whole `fonts` array in astro.config after the fix — every duplicate pair warns only once at first sight

Example fix

// before: two families fight over --font-sans
fonts: [
  { provider: fontProviders.google(), name: 'Inter', cssVariable: '--font-sans' },
  { provider: fontProviders.google(), name: 'Roboto', cssVariable: '--font-sans' },
]

// after: unique variables per family
fonts: [
  { provider: fontProviders.google(), name: 'Inter', cssVariable: '--font-inter' },
  { provider: fontProviders.google(), name: 'Roboto', cssVariable: '--font-roboto' },
]

// Fail fast in config when families reuse a cssVariable without matching name+provider
const variables = new Map<string, string>();
for (const f of fonts) {
  const prev = variables.get(f.cssVariable);
  const signature = `${f.name}|${f.provider}`;
  if (prev && prev !== signature) {
    throw new Error(`cssVariable ${f.cssVariable} reused by different families (${prev} vs ${signature})`);
  }
  variables.set(f.cssVariable, signature);
}

When it happens

Trigger: Two entries in the `fonts` config array sharing an explicit cssVariable while differing in `name` or `provider` — e.g., copy-pasting a family block and changing only the name but keeping `cssVariable: '--font-sans'`.

Common situations: Duplicating a family entry to add weights then forgetting to change the variable; switching a family from one provider to another while keeping the variable; iterating on font configs during setup.

Related errors

• These families will not be merged together. The last occurre
• No data found for font family ${bold(family.name)}. Review y
• ${bold(family.name)} font family cannot be retrieved by the
• FontFamilyNotFound
• The font file ${JSON.stringify(path)} referenced in your con

AI-assisted analysis of withastro/astro@52e6c34790 (2026-08-18). Data as JSON: /api/errors/b702fa001ca32ae0. Report an issue: GitHub.